chore(docs): Extract development documentation from README into new docs folder (#230)

andreiborza · smeubank · web-flow · commit 09e4c8aff177 · 2025-01-14T16:38:06.000+01:00
* chore(docs): Extract development documentation from README into new docs folder * Add CODEOWNER * add link to sourcemaps we only link to that release workflow page, which i think is meh * important note on checkout version @andreiborza should we update the example to use v4, latest version from the checkout action? * Formatting and further clarification on checkout action * Update organization auth token prerequisite --------- Co-authored-by: Steven Eubank <47563310+smeubank@users.noreply.github.com>
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -0,0 +1 @@
+*   @andreiborza
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
diff --git a/README.md b/README.md
@@ -1,6 +1,18 @@
+<p align="center">
+  <a href="https://sentry.io/?utm_source=github&utm_medium=logo" target="_blank">
+    <picture>
+      <source srcset="https://sentry-brand.storage.googleapis.com/sentry-logo-white.png" media="(prefers-color-scheme: dark)" />
+      <source srcset="https://sentry-brand.storage.googleapis.com/sentry-logo-black.png" media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)" />
+      <img src="https://sentry-brand.storage.googleapis.com/sentry-logo-black.png" alt="Sentry" width="280">
+    </picture>
+  </a>
+</p>
+
 # Sentry Release GitHub Action
 
-**NOTE**: Currently only available for Linux runners. See [this issue](https://github.com/getsentry/action-release/issues/58) for more details.
+> [!IMPORTANT]
+> This action is currently only available for Linux runners. 
+> See [this issue](https://github.com/getsentry/action-release/issues/58) for more details.
 
 Automatically create a Sentry release in a workflow.
 
@@ -11,26 +23,25 @@ A release is a version of your code that can be deployed to an environment. When
 - Resolve issues by including the issue number in your commit message
 - Receive email notifications when your code gets deployed
 
-Additionally, releases are used for applying source maps to minified JavaScript to view original, untransformed source code. You can learn more about releases in the [releases documentation](https://docs.sentry.io/workflow/releases).
+Additionally, releases are used for applying [source maps](https://docs.sentry.io/platforms/javascript/sourcemaps/) to minified JavaScript to view original, untransformed source code. You can learn more about releases in the [releases documentation](https://docs.sentry.io/workflow/releases).
 
 ## Prerequisites
 
-### Create a Sentry Internal Integration
-
-NOTE: You have to be an admin in your Sentry org to create this.
-
-For this action to communicate securely with Sentry, you'll need to create a new internal integration. In Sentry, navigate to: _Settings > Developer Settings > Custom Integrations > Create New Integration > Internal Integration_.
-
-Give your new integration a name (for example, "GitHub Action Release Integration”) and specify the necessary permissions. In this case, we need Admin access for “Release” and Read access for “Organization”.
+### Create an Organization Auth Token
 
-![View of internal integration permissions.](images/internal-integration-permissions.png)
-
-Click “Save” at the bottom of the page, then go back into your newly created integration and click "New Token". Grab this newly generated token and use it as your `SENTRY_AUTH_TOKEN`. We recommend you store this as an [encrypted secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions).
+> [!NOTE]
+> You have to be an admin in your Sentry org to create this.
+ 
+For this action to communicate securely with Sentry, you'll need to [create an organization auth token](https://docs.sentry.io/account/auth-tokens/#organization-auth-tokens).
+Copy the generated token and use it as your `SENTRY_AUTH_TOKEN`. We recommend storing it as an [encrypted secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions).
 
 ## Usage
 
 Adding the following to your workflow will create a new Sentry release and tell Sentry that you are deploying to the `production` environment.
-  
+
+> [!IMPORTANT]
+> Make sure you are using at least v3 of [actions/checkout](https://github.com/actions/checkout) with `fetch-depth: 0`, issues commonly occur with older versions.
+ 
 ```yaml
 - uses: actions/checkout@v3
   with:
@@ -106,124 +117,14 @@ Adding the following to your workflow will create a new Sentry release and tell
         SENTRY_URL: https://sentry.example.com/
     ```
 
-## Releases
-
-The `build.yml` workflow will build a Docker image every time a pull request merges to `master` and upload it to [the GitHub registry](https://github.com/orgs/getsentry/packages?repo_name=action-release), thus, effectively being live for everyone even if we do not bump the version.
-
-NOTE: Unfortunately, we only use the `latest` tag for the Docker image, thus, making use of a version with the action innefective (e.g. `v1` vs `v1.3.0`). See #129 on how to fix this.
-
-NOTE: Right now, our Docker image publishing is decoupled from `tag` creation in the repository. We should only publish a specific Docker tag when we create a tag (you can make GitHub workflows listen to this). See #102 for details. Once this is fixed merges to `master` will not make the Docker image live and the following paragraph will be legit.
-
-When you are ready to make a release, open a [new release checklist issue](https://github.com/getsentry/action-release/issues/new?assignees=&labels=&template=release-checklist.md&title=New+release+checklist+for+%5Bversion+number%5D) and follow the steps in there.
-
-The Docker build is [multi-staged](https://github.com/getsentry/action-release/blob/master/Dockerfile) in order to make the final image used by the action as small as possible to reduce network transfer (use `docker images` to see the sizes of the images).
-
-### End to end testing on GitHub's CI
-
-The first job in `test.yml` has instructions on how to tweak a job in order to execute your changes as part of the PR.
-
-NOTE: Contributors will need to create an internal integration in their Sentry org and need to be an admin. See `Prerequisites` section above.
-
-Members of this repo will not have to set anything up since [the integration](https://sentry-ecosystem.sentry.io/settings/developer-settings/end-to-end-action-release-integration-416eb2/) is already set-up. Just open the PR and you will see [a release created](https://sentry-ecosystem.sentry.io/releases/?project=4505075304693760) for your PR.
-
-## Development
-
-If your change impacts the options used for the action, you need to update the README.md with the new options.
-
-## Testing
-
-You can run the unit tests with `yarn test`.
-
-### Test your own repo against an action-release PR
-
-NOTE: This section has not been fully tested but it should work with a bit of investment.
-
-NOTE: This assumes that you have gone through the `Usage` section and have managed to get your Github repository to have worked with this action.
-
-NOTE: Once we start producing Docker images for PRs we can get rid of the need of using the `sed` command below.
-
-Step 1 - action-release changes (This is your PR with your code changes):
-* Make changes to your action-release branch and push it
-* Run this command, commit the changes and push it
-  * This will cause the action-release to be built using the `Dockerfile`
-  * You will need to revert this change once your changes are approved and ready to be merged
-
-```shell
-sed -i .backup 's|docker://ghcr.io/getsentry/action-release-image:latest|Dockerfile|' action.yml
-```
-
-Step 2 - Test out your action-release changes on your own repo
-* Get the sha for the latest commit on Step 1
-* Modify your usage of action-release to point to that commit
-  * If you're using a fork, edit the getsentry org in the string below
-
-```yml
-  - name: Sentry Release
-    uses: getsentry/action-release@<github_action_commit>
-    env:
-      # You will remove this in the next steps when ready
-      MOCK: true
-      SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
-      SENTRY_ORG: ${{ vars.SENTRY_ORG }}
-      # If you specify a Github environment for the branch from where you create
-      # releases from (e.g. master), you can then specify a repository-level variable
-      # for all other branches. This allows using a second project for end-to-end testing
-      SENTRY_PROJECT: ${{ vars.SENTRY_PROJECT }}
-```
-
-NOTE: If you want to do local testing read the next section, otherwise, keep reading.
-
-NOTE: Only remove `MOCK: true` once you follow the steps below that will allow you to use two different projects. This will avoid polutting your Sentry releases for your existing Sentry project.
-
-<!-- Add link to test.yml after PR 153 merges -->
-
-Step 3 - Create a new Sentry project under your existing Sentry org (only this one time)
-Step 4 - Create an environment variable in Github for the branch you release from (e.g. `master`) and define the same variable as a repository variable which all other branches will use (read: your PRs)
-
-<!-- <TODO add screenshot here> -->
-Step 5 - Comment out the MOCK env variable from step 2
-Step 6 - Push to Github and the CI will do an end-to-end run!
-
-NOTE: As mentioned, this section not been tested. Please try it out and let me know if it works for you.
-
-### Local testing via act
-
-NOTE: You should test out this whole section to see if it still makes sense to use this testing approach and/or if to only use the one above.
-
-[Here's a repo](https://github.com/scefali/github-actions-react/blob/master/.github/workflows/deploy.yml) you can clone to test out this section.
-
-Step 1 - Install `act` in Mac with:
-```bash
-brew install act
-```
-
-NOTE: Make sure you commit your changes in your branch before running `act`.
-
-Step 3 - Create an integration and set the SENTRY_AUTH_TOKEN (see `Usage` section in this doc)
-
-NOTE: If you have `direnv` installed, you can define the variable within your repo in an `.env` file.
-
-Step 4 - Run the action
-
-```bash
-act -s SENTRY_ORG={your_org_slug} -s SENTRY_PROJECT={your_project_slug}
-```
-
-NOTE: Make sure that `SENTRY_AUTH_TOKEN` is loaded as an env variable.
-NOTE: If you're running and M1 chipset instead of Intel you can ignore the following message:
-```
-WARN  ⚠ You are using Apple M1 chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'
-```
-
-Step 5 - Choose Medium Docker builds
 
 ## Contributing
 
-See the [Contributing Guide](https://github.com/getsentry/action-release/blob/master/CONTRIBUTING).
+See the [Contributing Guide](./CONTRIBUTING.md).
 
 ## License
 
-See the [License File](https://github.com/getsentry/action-release/blob/master/LICENSE).
+See the [License File](./LICENSE)
 
 ## Troubleshooting
 
diff --git a/docs/development.md b/docs/development.md
@@ -0,0 +1,118 @@
+# Development of `getsentry/action-release`
+
+This document aims to provide guidelines for maintainers and contains information on how to develop and test this action. 
+For info on how to release changes, follow [publishing-a-release](publishing-a-release.md).
+
+## Development
+
+The action is using `@sentry/cli` under the hood and is written in TypeScript. See `src/main.ts` to get started.
+
+Options to the action are exposed via `action.yml`, changes that impact options need to be documented in the `README.md`.
+
+Telemetry for internal development is collected using `@sentry/node`, see `src/telemetry.ts` for utilities.
+
+## Testing
+
+You can run unit tests with `yarn test`.
+
+### E2E testing on GitHub's CI
+
+The first job in [test.yml](../.github/workflows/test.yml) has instructions on how to tweak a job in order to execute your changes as part of the PR.
+
+> [!NOTE]  
+> Contributors will need to create an internal integration in their Sentry org and need to be an admin. 
+> See [#Prerequisites](../README.md#prerequisites).
+
+Members of this repo will not have to set anything up since [the integration](https://sentry-ecosystem.sentry.io/settings/developer-settings/end-to-end-action-release-integration-416eb2/) is already set-up. Just open the PR and you will see [a release created](https://sentry-ecosystem.sentry.io/releases/?project=4505075304693760) for your PR.
+
+### Test your own repo against an action-release PR
+
+> [!NOTE]
+> This assumes that you have gone through the [#Usage](../README.md#usage) section and have managed to get your GitHub repository to have worked with this action.
+
+> [!NOTE]
+> Once we start producing Docker images for PRs we can get rid of the need of using the `sed` command below.
+
+**Step 1**  
+* Create a branch, make changes and push it
+* Run this command, commit the changes and push it
+  * This will cause the action-release to be built using the `Dockerfile`
+  * You will need to revert this change once your changes are approved and ready to be merged
+
+```shell
+sed -i .backup 's|docker://ghcr.io/getsentry/action-release-image:latest|Dockerfile|' action.yml
+```
+
+**Step 2**  
+Test out your action-release changes on your own repo.
+* Get the sha for the latest commit on **Step 1**
+* Modify your usage of action-release to point to that commit (if you're using a fork, edit the `getsentry` org in the string below)
+
+Example:
+
+```yml
+  - name: Sentry Release
+    uses: getsentry/action-release@<latest commit sha>
+    env:
+      # You will remove this in the next steps when ready
+      MOCK: true
+      SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
+      SENTRY_ORG: ${{ vars.SENTRY_ORG }}
+      # If you specify a GitHub environment for the branch from where you create
+      # releases from (e.g. master), you can then specify a repository-level variable
+      # for all other branches. This allows using a second project for end-to-end testing
+      SENTRY_PROJECT: ${{ vars.SENTRY_PROJECT }}
+```
+
+> [!NOTE]
+> If you want to locally test the action, read the next section, otherwise, keep reading.
+
+> [!NOTE]
+> Only remove `MOCK: true` once you follow the steps below that will allow you to use two different projects. This will avoid polluting your Sentry releases for your existing Sentry project.
+
+**Step 3**  
+Create a new Sentry project under your existing Sentry org (only this one time).
+
+**Step 4**  
+Create an environment variable in GitHub for the branch you release from (e.g. `master`) and define the same variable as a repository variable which all other branches will use (i.e. your PR's branch)
+
+**Step 5**  
+Comment out the MOCK env variable from **Step 2**.
+
+**Step 6**  
+Push to GitHub and the CI will do an end-to-end run!
+
+### Local testing via act
+
+Alternatively, you can test the action locally using [act](https://github.com/nektos/act).
+
+To get started, you can clone [this sample repo](https://github.com/scefali/github-actions-react/blob/master/.github/workflows/deploy.yml) to test locally.
+
+**Step 1**  
+Install `act`.
+
+```bash
+brew install act
+```
+
+> [!NOTE]
+> Make sure you commit your changes in your branch before running `act`.
+
+**Step 3**  
+Create an integration and set the SENTRY_AUTH_TOKEN (see [#Usage](../README.md#usage)).
+
+> [!NOTE]
+> If you have `direnv` installed, you can define the variable within your repo in an `.env` file.
+
+**Step 4**  
+Run the action.
+
+```bash
+act -s SENTRY_ORG={your_org_slug} -s SENTRY_PROJECT={your_project_slug}
+```
+
+> [!NOTE]
+> Make sure that `SENTRY_AUTH_TOKEN` is loaded as an env variable.
+
+**Step 5**  
+Choose Medium Docker builds.
diff --git a/docs/publishing-a-release.md b/docs/publishing-a-release.md
@@ -0,0 +1,24 @@
+# Publishing a release
+
+The [build.yml](../.github/workflows/build.yml) workflow will build a Docker image every time a pull request merges to `master` and upload it to [the GitHub registry](https://github.com/orgs/getsentry/packages?repo_name=action-release).
+
+> [!WARNING]
+> Merging pull requests into `master` means changes are live for anyone who uses the action regardless of bumping the version.
+> Be extremely careful and intentional with changes and ensure properly testing them before merging, see [#Testing](development.md#testing) for more info.
+effectively being live for everyone even if we do not bump the version.
+
+> [!NOTE]
+> Unfortunately, we only use the `latest` tag for the Docker image, thus, making use of a version with the action ineffective (e.g. `v1` vs `v1.3.0`). 
+> See #129 on how to fix this.
+
+> [!NOTE]
+> At the moment our Docker image publishing is decoupled from `tag` creation in the repository. 
+> We should only publish a specific Docker tag when we create a tag (you can make GitHub workflows listen to this). See #102 for details. 
+> Once this is fixed, merges to `master` will not make the Docker image live.
+
+When you are ready to make a release, open a [new release checklist issue](https://github.com/getsentry/action-release/issues/new?assignees=&labels=&template=release-checklist.md&title=New+release+checklist+for+%5Bversion+number%5D) and follow the steps in there.
+
+> [!NOTE]
+> At the moment releases are only used to inform users of changes.
+
+The Docker build is [multi-staged](https://github.com/getsentry/action-release/blob/master/Dockerfile) in order to make the final image used by the action as small as possible to reduce network transfer (use `docker images` to see the sizes of the images).
