chore(docs): Extract development documentation from README into new docs folder (#230)
* 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 <[email protected]>
This commit is contained in:
Andrei
@@ -0,0 +1 @@
|
||||
* @andreiborza
|
||||
|
||||
@@ -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
|
||||
### Create an Organization Auth Token
|
||||
|
||||
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”.
|
||||
|
||||
|
||||
|
||||
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
|
||||
|
||||
|
||||
@@ -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.
|
||||
@@ -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).
|
||||
Reference in New Issue
Block a user