Skip to content

Commit

Permalink
Merge pull request #16 from touchlab/dev
Browse files Browse the repository at this point in the history 
Dev
  • Loading branch information
@kpgalligan
kpgalligan authored Aug 29, 2024
2 parents fbb80f9 + 424bc1b commit ce867ea
Show file tree
Hide file tree
Showing 5 changed files with 85 additions and 253 deletions.
234 changes: 14 additions & 220 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,229 +1,23 @@
# Create a GitHub Action Using TypeScript
# Kotlin Multiplatform SPM publishing from a local repo

[![GitHub Super-Linter](https://github.com/actions/typescript-action/actions/workflows/linter.yml/badge.svg)](https://github.com/super-linter/super-linter)
![CI](https://github.com/actions/typescript-action/actions/workflows/ci.yml/badge.svg)
[![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)
[![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)
[![Coverage](./badges/coverage.svg)](./badges/coverage.svg)
## Main Docs

Use this template to bootstrap the creation of a TypeScript action. :rocket:
This plugin helps support [KMMBridge](https://touchlab.co/kmmbridge/) features. To understand how to use it, please follow those docs and tutorials.

This template includes compilation support, tests, a validation workflow,
publishing, and versioning guidance.
## Overview

If you are new, there's also a simpler introduction in the
[Hello world JavaScript action repository](https://github.com/actions/hello-world-javascript-action).
When publishing SPM binaries for KMP, you need a `Package.swift` file pointing at your binary, and that needs to be referenced by a git tag.

## Create Your Own Action
When using GitHub Releases to store your binary zip, there's an issue. You need a release to push to, and you need the "real" URL of the artifact, which you cannot determine before pushing the file.

To create your own action, you can use this repository as a template! Just
follow the below instructions:
So, to use GitHub Releases, you'll need to force-update the git tag associated with the GitHub Release. This action will do that for you.

1. Click the **Use this template** button at the top of the repository
1. Select **Create a new repository**
1. Select an owner and name for your new repository
1. Click **Create repository**
1. Clone your new repository
Also, this action assumes you want to support a local-dev workflow for testing the KMP code. As such, the tagged commit created for the SPM release is not pushed to any specific branch. The commit referenced by the tag exists, but is not part of any branch in the repo.

> [!IMPORTANT]
>
> Make sure to remove or update the [`CODEOWNERS`](./CODEOWNERS) file! For
> details on how to use this file, see
> [About code owners](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners).
## Arguments

## Initial Setup

After you've cloned the repository to your local machine or codespace, you'll
need to perform some initial setup steps before you can develop your action.

> [!NOTE]
>
> You'll need to have a reasonably modern version of
> [Node.js](https://nodejs.org) handy (20.x or later should work!). If you are
> using a version manager like [`nodenv`](https://github.com/nodenv/nodenv) or
> [`nvm`](https://github.com/nvm-sh/nvm), this template has a `.node-version`
> file at the root of the repository that will be used to automatically switch
> to the correct version when you `cd` into the repository. Additionally, this
> `.node-version` file is used by GitHub Actions in any `actions/setup-node`
> actions.
1. :hammer_and_wrench: Install the dependencies

```bash
npm install
```

1. :building_construction: Package the TypeScript for distribution

```bash
npm run bundle
```

1. :white_check_mark: Run the tests

```bash
$ npm test

PASS ./index.test.js
✓ throws invalid number (3ms)
✓ wait 500 ms (504ms)
✓ test runs (95ms)

...
```

## Update the Action Metadata

The [`action.yml`](action.yml) file defines metadata about your action, such as
input(s) and output(s). For details about this file, see
[Metadata syntax for GitHub Actions](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions).

When you copy this repository, update `action.yml` with the name, description,
inputs, and outputs for your action.

## Update the Action Code

The [`src/`](./src/) directory is the heart of your action! This contains the
source code that will be run when your action is invoked. You can replace the
contents of this directory with your own code.

There are a few things to keep in mind when writing your action code:

- Most GitHub Actions toolkit and CI/CD operations are processed asynchronously.
In `main.ts`, you will see that the action is run in an `async` function.

```javascript
import * as core from '@actions/core'
//...

async function run() {
try {
//...
} catch (error) {
core.setFailed(error.message)
}
}
```

For more information about the GitHub Actions toolkit, see the
[documentation](https://github.com/actions/toolkit/blob/master/README.md).

So, what are you waiting for? Go ahead and start customizing your action!

1. Create a new branch

```bash
git checkout -b releases/v1
```

1. Replace the contents of `src/` with your action code
1. Add tests to `__tests__/` for your source code
1. Format, test, and build the action

```bash
npm run all
```

> This step is important! It will run [`ncc`](https://github.com/vercel/ncc)
> to build the final JavaScript action code with all dependencies included.
> If you do not run this step, your action will not work correctly when it is
> used in a workflow. This step also includes the `--license` option for
> `ncc`, which will create a license file for all of the production node
> modules used in your project.
1. Commit your changes

```bash
git add .
git commit -m "My first action is ready!"
```

1. Push them to your repository

```bash
git push -u origin releases/v1
```

1. Create a pull request and get feedback on your action
1. Merge the pull request into the `main` branch

Your action is now published! :rocket:

For information about versioning your action, see
[Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md)
in the GitHub Actions toolkit.

## Validate the Action

You can now validate the action by referencing it in a workflow file. For
example, [`ci.yml`](./.github/workflows/ci.yml) demonstrates how to reference an
action in the same repository.

```yaml
steps:
- name: Checkout
id: checkout
uses: actions/checkout@v4

- name: Test Local Action
id: test-action
uses: ./
with:
milliseconds: 1000

- name: Print Output
id: output
run: echo "${{ steps.test-action.outputs.time }}"
```
For example workflow runs, check out the
[Actions tab](https://github.com/actions/typescript-action/actions)! :rocket:
## Usage
After testing, you can create version tag(s) that developers can use to
reference different stable versions of your action. For more information, see
[Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md)
in the GitHub Actions toolkit.
To include the action in a workflow in another repository, you can use the
`uses` syntax with the `@` symbol to reference a specific branch, tag, or commit
hash.

```yaml
steps:
- name: Checkout
id: checkout
uses: actions/checkout@v4
- name: Test Local Action
id: test-action
uses: actions/typescript-action@v1 # Commit with the `v1` tag
with:
milliseconds: 1000

- name: Print Output
id: output
run: echo "${{ steps.test-action.outputs.time }}"
```
## Publishing a New Release
This project includes a helper script, [`script/release`](./script/release)
designed to streamline the process of tagging and pushing new releases for
GitHub Actions.

GitHub Actions allows users to select a specific version of the action to use,
based on release tags. This script simplifies this process by performing the
following steps:

1. **Retrieving the latest release tag:** The script starts by fetching the most
recent release tag by looking at the local data available in your repository.
1. **Prompting for a new release tag:** The user is then prompted to enter a new
release tag. To assist with this, the script displays the latest release tag
and provides a regular expression to validate the format of the new tag.
1. **Tagging the new release:** Once a valid new tag is entered, the script tags
the new release.
1. **Pushing the new tag to the remote:** Finally, the script pushes the new tag
to the remote repository. From here, you will need to create a new release in
GitHub and users can easily reference the new tag in their workflows.
* `commitMessage` - Required - Message for the commit which updates the `Package.swift` file
* `tagMessage` - Optional - Message for the version tag commit. Defaults to "Version ${tagVersion}"
* `tagVersion` - Required - Version string to use in the tag. Should follow [semver rules](https://semver.org/).
* `branchName` - Optional - Branch to create and build with. Safe to ignore this.
* `remote` - Optional - Remote to push to. Default to "origin".
24 changes: 13 additions & 11 deletions action.yml
View file
Original file line number Diff line number Diff line change
@@ -1,25 +1,27 @@
name: 'KXCBridge: Tag Release'
description: 'Tag version for SPM'
name: 'KMMBridge: Local SPM Publishing Support'
description: 'Commit and tag SPM version.'
author: 'Kevin Galligan'

# Add your action's branding here. This will appear on the GitHub Marketplace.
branding:
icon: 'heart'
color: 'red'
icon: 'git-branch'
color: 'orange'

inputs:
commitMessage:
description: 'Message for Package.swift commit'
description: 'Message for the commit which updates the `Package.swift` file.'
required: true
tagMessage:
description: 'Message for release tag'
required: true
description: 'Message for the release tag. Defaults to "Version ${tagVersion}".'
required: false
tagVersion:
description: 'The release version'
description: 'Version string to use in the tag. Should follow [semver rules](https://semver.org/).'
required: true
branchName:
description: 'Branch name'
required: true
description: 'Branch to create and build with. Safe to ignore this.'
required: false
remote:
description: 'Remote to push to. Default to "origin".'
required: false

runs:
using: node20
Expand Down
36 changes: 26 additions & 10 deletions dist/index.js
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion dist/index.js.map
View file

Large diffs are not rendered by default.

42 changes: 31 additions & 11 deletions src/main.ts
View file
Original file line number Diff line number Diff line change
@@ -1,29 +1,49 @@
import * as core from '@actions/core'
import simpleGit from 'simple-git'

Check failure on line 2 in src/main.ts

View workflow job for this annotation

GitHub Actions / Lint Codebase 

Using exported name 'simpleGit' as identifier for default export

function notEmpty(p: string | undefined) {

Check failure on line 4 in src/main.ts

View workflow job for this annotation

GitHub Actions / Lint Codebase 

Missing return type on function
return p && p.trim().length > 0
}

function assertNotEmpty(p: string | undefined, message: string) {

Check failure on line 8 in src/main.ts

View workflow job for this annotation

GitHub Actions / Lint Codebase 

Missing return type on function
if (!notEmpty(p)) {
core.setFailed(message)
throw new Error(message)
}
}

export async function run(): Promise<void> {
try {
const commitMessage: string = core.getInput('commitMessage')
const tagMessage: string = core.getInput('tagMessage')
const tagVersion: string = core.getInput('tagVersion')
const branchName: string = core.getInput('branchName')
const commitMessage: string = core.getInput('commitMessage')
let tagMessage: string = core.getInput('tagMessage')
const tagVersion: string = core.getInput('tagVersion')
let branchName: string = core.getInput('branchName')
let remote: string = core.getInput('remote')

core.debug(`commitMessage: ${commitMessage}`)
core.debug(`tagMessage: ${tagMessage}`)
core.debug(`tagVersion: ${tagVersion}`)
core.debug(`branchName: ${branchName}`)
core.debug(`remote: ${remote}`)

core.debug(`commitMessage: ${commitMessage}`)
core.debug(`tagMessage: ${tagMessage}`)
core.debug(`tagVersion: ${tagVersion}`)
core.debug(`branchName: ${branchName}`)
tagMessage = notEmpty(tagMessage) ? tagMessage : `Version ${tagVersion}`
remote = notEmpty(remote) ? remote : 'origin'
branchName = notEmpty(branchName) ? branchName : `build-${tagVersion}`

assertNotEmpty(commitMessage, '\'commitMessage\' cannot be empty')

Check failure on line 32 in src/main.ts

View workflow job for this annotation

GitHub Actions / Lint Codebase 

Replace `'\'commitMessage\'·cannot·be·empty'` with `"'commitMessage'·cannot·be·empty"`
assertNotEmpty(tagVersion, '\'tagVersion\' cannot be empty')

Check failure on line 33 in src/main.ts

View workflow job for this annotation

GitHub Actions / Lint Codebase 

Replace `'\'tagVersion\'·cannot·be·empty'` with `"'tagVersion'·cannot·be·empty"`

try {
const git = simpleGit()

await git.pull()
await git.pull(remote)

await git.checkoutLocalBranch(branchName)

await git.add('.')
await git.commit(commitMessage)

await git.raw('tag', '-fa', tagVersion, '-m', tagMessage)
await git.raw('push', 'origin', '-f', `refs/tags/${tagVersion}`)
await git.raw('push', remote, '-f', `refs/tags/${tagVersion}`)
} catch (error) {
// Fail the workflow run if an error occurs
if (error instanceof Error) core.setFailed(error.message)
Expand Down

0 comments on commit ce867ea

Please sign in to comment.