Skip to content

Commit 63cb7e5

Browse files
ShtibsDevShtibsDev
committed
docs: 📝 Update action.yml, README.md and CODEOWNERS
1 parent 0cc6d3e commit 63cb7e5

File tree

3 files changed

+121
-225
lines changed

3 files changed

+121
-225
lines changed

‎CODEOWNERS

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
# Repository CODEOWNERS
22

33
* @actions/actions-runtime
4-
* @ncalteen
4+
* @ShtibsDev

‎README.md

Lines changed: 81 additions & 209 deletions
Original file line numberDiff line numberDiff line change
@@ -1,230 +1,102 @@
1-
# Create a GitHub Action Using TypeScript
1+
This GitHub Action (written in Typescript) wraps the
2+
[Octokit Create a Release](https://docs.github.com/en/rest/releases/releases?apiVersion=2022-11-28#create-a-release)
3+
endpoint, to allow you to leverage GitHub Actions to create releases.
24

3-
[![GitHub Super-Linter](https://github.com/actions/typescript-action/actions/workflows/linter.yml/badge.svg)](https://github.com/super-linter/super-linter)
4-
![CI](https://github.com/actions/typescript-action/actions/workflows/ci.yml/badge.svg)
5-
[![Check dist/](https://github.com/actions/typescript-action/actions/workflows/check-dist.yml/badge.svg)](https://github.com/actions/typescript-action/actions/workflows/check-dist.yml)
6-
[![CodeQL](https://github.com/actions/typescript-action/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/actions/typescript-action/actions/workflows/codeql-analysis.yml)
7-
[![Coverage](./badges/coverage.svg)](./badges/coverage.svg)
5+
This action is an up-to-date version of the archived first-party
6+
[Create Release](https://github.com/actions/create-release) action by Github. All functionality is the same, but the
7+
action uses the [Octokit](https://github.com/octokit/octokit.js) api instead of the old Github api.
88

9-
Use this template to bootstrap the creation of a TypeScript action. :rocket:
9+
<a href="https://github.com/actions/create-release"><img alt="GitHub Actions status" src="https://github.com/actions/create-release/workflows/Tests/badge.svg"></a>
1010

11-
This template includes compilation support, tests, a validation workflow,
12-
publishing, and versioning guidance.
13-
14-
If you are new, there's also a simpler introduction in the
15-
[Hello world JavaScript action repository](https://github.com/actions/hello-world-javascript-action).
16-
17-
## Create Your Own Action
18-
19-
To create your own action, you can use this repository as a template! Just
20-
follow the below instructions:
21-
22-
1. Click the **Use this template** button at the top of the repository
23-
1. Select **Create a new repository**
24-
1. Select an owner and name for your new repository
25-
1. Click **Create repository**
26-
1. Clone your new repository
27-
28-
> [!IMPORTANT]
29-
>
30-
> Make sure to remove or update the [`CODEOWNERS`](./CODEOWNERS) file! For
31-
> details on how to use this file, see
32-
> [About code owners](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners).
33-
34-
## Initial Setup
35-
36-
After you've cloned the repository to your local machine or codespace, you'll
37-
need to perform some initial setup steps before you can develop your action.
38-
39-
> [!NOTE]
40-
>
41-
> You'll need to have a reasonably modern version of
42-
> [Node.js](https://nodejs.org) handy (20.x or later should work!). If you are
43-
> using a version manager like [`nodenv`](https://github.com/nodenv/nodenv) or
44-
> [`nvm`](https://github.com/nvm-sh/nvm), this template has a `.node-version`
45-
> file at the root of the repository that will be used to automatically switch
46-
> to the correct version when you `cd` into the repository. Additionally, this
47-
> `.node-version` file is used by GitHub Actions in any `actions/setup-node`
48-
> actions.
49-
50-
1. :hammer_and_wrench: Install the dependencies
51-
52-
```bash
53-
npm install
54-
```
55-
56-
1. :building_construction: Package the TypeScript for distribution
57-
58-
```bash
59-
npm run bundle
60-
```
61-
62-
1. :white_check_mark: Run the tests
63-
64-
```bash
65-
$ npm test
66-
67-
PASS ./index.test.js
68-
✓ throws invalid number (3ms)
69-
✓ wait 500 ms (504ms)
70-
✓ test runs (95ms)
71-
72-
...
73-
```
74-
75-
## Update the Action Metadata
76-
77-
The [`action.yml`](action.yml) file defines metadata about your action, such as
78-
input(s) and output(s). For details about this file, see
79-
[Metadata syntax for GitHub Actions](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions).
80-
81-
When you copy this repository, update `action.yml` with the name, description,
82-
inputs, and outputs for your action.
83-
84-
## Update the Action Code
85-
86-
The [`src/`](./src/) directory is the heart of your action! This contains the
87-
source code that will be run when your action is invoked. You can replace the
88-
contents of this directory with your own code.
89-
90-
There are a few things to keep in mind when writing your action code:
91-
92-
- Most GitHub Actions toolkit and CI/CD operations are processed asynchronously.
93-
In `main.ts`, you will see that the action is run in an `async` function.
94-
95-
```javascript
96-
import * as core from '@actions/core'
97-
//...
98-
99-
async function run() {
100-
try {
101-
//...
102-
} catch (error) {
103-
core.setFailed(error.message)
104-
}
105-
}
106-
```
107-
108-
For more information about the GitHub Actions toolkit, see the
109-
[documentation](https://github.com/actions/toolkit/blob/master/README.md).
110-
111-
So, what are you waiting for? Go ahead and start customizing your action!
112-
113-
1. Create a new branch
114-
115-
```bash
116-
git checkout -b releases/v1
117-
```
11+
## Usage
11812

119-
1. Replace the contents of `src/` with your action code
120-
1. Add tests to `__tests__/` for your source code
121-
1. Format, test, and build the action
13+
### Pre-requisites
12214

123-
```bash
124-
npm run all
125-
```
15+
Create a workflow `.yml` file in your `.github/workflows` directory. An
16+
[example workflow](#example-workflow---create-a-release) is available below. For more information, reference the GitHub
17+
Help Documentation for
18+
[Creating a workflow file](https://help.github.com/en/articles/configuring-a-workflow#creating-a-workflow-file).
12619

127-
> [!WARNING]
128-
>
129-
> This step is important! It will run [`ncc`](https://github.com/vercel/ncc)
130-
> to build the final JavaScript action code with all dependencies included.
131-
> If you do not run this step, your action will not work correctly when it is
132-
> used in a workflow. This step also includes the `--license` option for
133-
> `ncc`, which will create a license file for all of the production node
134-
> modules used in your project.
20+
### Inputs
13521

136-
1. Commit your changes
22+
For more information on these inputs, see the [API Documentation](https://developer.github.com/v3/repos/releases/#input)
13723

138-
```bash
139-
git add .
140-
git commit -m "My first action is ready!"
141-
```
24+
- `tag_name`: The name of the tag for this release
25+
- `release_name`: The name of the release
26+
- `body`: Text describing the contents of the release. Optional, and not needed if using `body_path`.
27+
- `body_path`: A file with contents describing the release. Optional, and not needed if using `body`.
28+
- `draft`: `true` to create a draft (unpublished) release, `false` to create a published one. Default: `false`
29+
- `prerelease`: `true` to identify the release as a prerelease. `false` to identify the release as a full release.
30+
Default: `false`
31+
- `commitish` : Any branch or commit SHA the Git tag is created from, unused if the Git tag already exists. Default: SHA
32+
of current commit
33+
- `owner`: The name of the owner of the repo. Used to identify the owner of the repository. Used when cutting releases
34+
for external repositories. Default: Current owner
35+
- `repo`: The name of the repository. Used to identify the repository on which to release. Used when cutting releases
36+
for external repositories. Default: Current repository
14237

143-
1. Push them to your repository
38+
#### `body_path`
14439

145-
```bash
146-
git push -u origin releases/v1
147-
```
40+
The `body_path` is valuable for dynamically creating a `.md` within code commits and even within the Github Action steps
41+
leading up to the `create-release`.
14842

149-
1. Create a pull request and get feedback on your action
150-
1. Merge the pull request into the `main` branch
43+
### Outputs
15144

152-
Your action is now published! :rocket:
45+
For more information on these outputs, see the
46+
[API Documentation](https://docs.github.com/en/rest/releases/releases?apiVersion=2022-11-28#response-4) for an example
47+
of what these outputs look like
15348

154-
For information about versioning your action, see
155-
[Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md)
156-
in the GitHub Actions toolkit.
49+
- `id`: The release ID
50+
- `html_url`: The URL users can navigate to in order to view the release. i.e.
51+
`https://github.com/octocat/Hello-World/releases/v1.0.0`
52+
- `upload_url`: The URL for uploading assets to the release, which could be used by GitHub Actions for additional uses,
53+
for example the [`@actions/upload-release-asset`](https://www.github.com/actions/upload-release-asset) GitHub Action
15754

158-
## Validate the Action
55+
### Example workflow - create a release
15956

160-
You can now validate the action by referencing it in a workflow file. For
161-
example, [`ci.yml`](./.github/workflows/ci.yml) demonstrates how to reference an
162-
action in the same repository.
57+
On every `push` to a tag matching the pattern `v*`,
58+
[create a release](https://docs.github.com/en/rest/releases/releases?apiVersion=2022-11-28#create-a-release):
16359

16460
```yaml
165-
steps:
166-
- name: Checkout
167-
id: checkout
168-
uses: actions/checkout@v4
169-
170-
- name: Test Local Action
171-
id: test-action
172-
uses: ./
173-
with:
174-
milliseconds: 1000
175-
176-
- name: Print Output
177-
id: output
178-
run: echo "${{ steps.test-action.outputs.time }}"
61+
on:
62+
push:
63+
# Sequence of patterns matched against refs/tags
64+
tags:
65+
- 'v*' # Push events to matching v*, i.e. v1.0, v20.15.10
66+
67+
name: Create Release
68+
69+
jobs:
70+
build:
71+
name: Create Release
72+
runs-on: ubuntu-latest
73+
steps:
74+
- name: Checkout code
75+
uses: actions/checkout@v2
76+
- name: Create Release
77+
id: create_release
78+
uses: actions/create-release@v1
79+
env:
80+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # This token is provided by Actions, you do not need to create your own token
81+
with:
82+
tag_name: ${{ github.ref }}
83+
release_name: Release ${{ github.ref }}
84+
body: |
85+
Changes in this Release
86+
- First Change
87+
- Second Change
88+
draft: false
89+
prerelease: false
17990
```
18091
181-
For example workflow runs, check out the
182-
[Actions tab](https://github.com/actions/typescript-action/actions)! :rocket:
183-
184-
## Usage
92+
This will create a [Release](https://help.github.com/en/articles/creating-releases), as well as a
93+
[`release` event](https://developer.github.com/v3/activity/events/types/#releaseevent), which could be handled by a
94+
third party service, or by GitHub Actions for additional uses, for example the
95+
[`@actions/upload-release-asset`](https://www.github.com/actions/upload-release-asset) GitHub Action. This uses the
96+
`GITHUB_TOKEN` provided by the
97+
[virtual environment](https://help.github.com/en/github/automating-your-workflow-with-github-actions/virtual-environments-for-github-actions#github_token-secret),
98+
so no new token is needed.
18599

186-
After testing, you can create version tag(s) that developers can use to
187-
reference different stable versions of your action. For more information, see
188-
[Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md)
189-
in the GitHub Actions toolkit.
190-
191-
To include the action in a workflow in another repository, you can use the
192-
`uses` syntax with the `@` symbol to reference a specific branch, tag, or commit
193-
hash.
194-
195-
```yaml
196-
steps:
197-
- name: Checkout
198-
id: checkout
199-
uses: actions/checkout@v4
200-
201-
- name: Test Local Action
202-
id: test-action
203-
uses: actions/typescript-action@v1 # Commit with the `v1` tag
204-
with:
205-
milliseconds: 1000
206-
207-
- name: Print Output
208-
id: output
209-
run: echo "${{ steps.test-action.outputs.time }}"
210-
```
100+
## License
211101

212-
## Publishing a new release
213-
214-
This project includes a helper script designed to streamline the process of
215-
tagging and pushing new releases for GitHub Actions.
216-
217-
GitHub Actions allows users to select a specific version of the action to use,
218-
based on release tags. Our script simplifies this process by performing the
219-
following steps:
220-
221-
1. **Retrieving the latest release tag:** The script starts by fetching the most
222-
recent release tag by looking at the local data available in your repository.
223-
1. **Prompting for a new release tag:** The user is then prompted to enter a new
224-
release tag. To assist with this, the script displays the latest release tag
225-
and provides a regular expression to validate the format of the new tag.
226-
1. **Tagging the new release:** Once a valid new tag is entered, the script tags
227-
the new release.
228-
1. **Pushing the new tag to the remote:** Finally, the script pushes the new tag
229-
to the remote repository. From here, you will need to create a new release in
230-
GitHub and users can easily reference the new tag in their workflows.
102+
The scripts and documentation in this project are released under the [MIT License](LICENSE)

‎action.yml

Lines changed: 39 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,47 @@
1-
name: 'The name of your action here'
2-
description: 'Provide a description here'
3-
author: 'Your name or organization here'
1+
name: "Create a release"
2+
description: "Create a release for a tag in your repository. An updated version of the original first-party"
3+
author: "ShtibsDev"
44

5-
# Add your action's branding here. This will appear on the GitHub Marketplace.
65
branding:
7-
icon: 'heart'
8-
color: 'red'
9-
10-
# Define your inputs here.
6+
icon: tag
7+
color: "gray-dark"
118
inputs:
12-
milliseconds:
13-
description: 'Your input description here'
9+
tag_name:
10+
description: "The name of the tag. This should come from the webhook payload, `github.GITHUB_REF` when a user pushes a new tag"
1411
required: true
15-
default: '1000'
16-
17-
# Define your outputs here.
12+
release_name:
13+
description: "The name of the release. For example, `Release v1.0.1`"
14+
required: true
15+
body:
16+
description: "Text describing the contents of the tag."
17+
required: false
18+
body_path:
19+
description: "Path to file with information about the tag."
20+
required: false
21+
draft:
22+
description: "`true` to create a draft (unpublished) release, `false` to create a published one. Default: `false`"
23+
required: false
24+
default: "false"
25+
prerelease:
26+
description: "`true` to identify the release as a prerelease. `false` to identify the release as a full release. Default: `false`"
27+
required: false
28+
default: "false"
29+
commitish:
30+
description: "Any branch or commit SHA the Git tag is created from, unused if the Git tag already exists. Default: SHA of current commit"
31+
required: false
32+
owner:
33+
description: "Owner of the repository if it is not the current one"
34+
required: false
35+
repo:
36+
description: "Repository on which to release. Used only if you want to create the release on another repo"
37+
required: false
1838
outputs:
19-
time:
20-
description: 'Your output description here'
39+
id:
40+
description: "The ID of the created Release"
41+
html_url:
42+
description: "The URL users can navigate to in order to view the release"
43+
upload_url:
44+
description: "The URL for uploading assets to the release"
2145

2246
runs:
2347
using: node20

0 commit comments

Comments
 (0)