Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .idea/.gitignore

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

8 changes: 8 additions & 0 deletions .idea/create-linked-shortcut-story.iml

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

6 changes: 6 additions & 0 deletions .idea/inspectionProfiles/Project_Default.xml

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

8 changes: 8 additions & 0 deletions .idea/modules.xml

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

6 changes: 6 additions & 0 deletions .idea/vcs.xml

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

80 changes: 40 additions & 40 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,16 @@
# Create Linked Clubhouse Story
# Create Linked Shortcut Story

This is a [GitHub Action](https://github.com/features/actions) that will
automatically create a story on [Clubhouse](https://clubhouse.io/) when
automatically create a story on [Shortcut](https://clubhouse.io/) when
a pull request is opened, unless the pull request already has a link to
a Clubhouse story in the description.
a Shortcut story in the description.

## Basic Usage

[Create a Clubhouse API token](https://app.clubhouse.io/settings/account/api-tokens),
[Create a Shortcut API token](https://app.clubhouse.io/settings/account/api-tokens),
and store it as an encrypted secret in your GitHub repository settings.
[Check the GitHub documentation for how to create an encrypted secret.](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets#creating-encrypted-secrets)
Name this secret `CLUBHOUSE_TOKEN`.
Name this secret `SHORTCUT_TOKEN`.

Create a file named `clubhouse.yml` in the `.github/workflows` directory of your repository. Put in the following content:

Expand All @@ -26,28 +26,28 @@ jobs:
- uses: singingwolfboy/[email protected]
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
clubhouse-token: ${{ secrets.CLUBHOUSE_TOKEN }}
clubhouse-token: ${{ secrets.SHORTCUT_TOKEN }}
project-name: Engineering
opened-state-name: Started
merged-state-name: Done
closed-state-name: Abandoned
```

The `project-name` variable should contain the name of the Clubhouse project
that you want the Clubhouse story to be associated with. The
The `project-name` variable should contain the name of the Shortcut project
that you want the Shortcut story to be associated with. The
`opened-state-name`, `merged-state-name`, and `closed-state-name` variables
should contain the name of the state that you want the Clubhouse story to
should contain the name of the state that you want the Shortcut story to
be in when the pull request is opened, merged, and closed, respectively.

## Disabled for Built-In Integration

[Clubhouse already has an integration with GitHub.](https://help.clubhouse.io/hc/en-us/articles/207540323-Using-The-Clubhouse-GitHub-Integration)
It works for the opposite use-case, assuming that the Clubhouse story exists
[Shortcut already has an integration with GitHub.](https://help.clubhouse.io/hc/en-us/articles/207540323-Using-The-Shortcut-GitHub-Integration)
It works for the opposite use-case, assuming that the Shortcut story exists
_before_ the pull request is created.

This Action will specifically check for branch names that follow the naming
convention for this built-in integration. Any branch name that contains
`sc-####` will be ignored by this Action, on the assumption that a Clubhouse
`sc-####` will be ignored by this Action, on the assumption that a Shortcut
story already exists for the pull request. The `sc-####` must be separated
from leading or following text with either a `/` or a `-`. So, branches
named `sc-1`, `prefix/sc-23`, `prefix-sc-123`, `sc-3456/suffix`, `sc-3456-suffux`,
Expand All @@ -62,37 +62,37 @@ variable, like this:
- uses: singingwolfboy/[email protected]
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
clubhouse-token: ${{ secrets.CLUBHOUSE_TOKEN }}
clubhouse-token: ${{ secrets.SHORTCUT_TOKEN }}
project-name: Engineering
opened-state-name: Started
merged-state-name: Done
closed-state-name: Abandoned
comment-template: >-
Thanks for the pull request! [I've created a Clubhouse story
Thanks for the pull request! [I've created a Shortcut story
for you.]({{{ story.app_url }}})
```

This comment template is processed using the [Mustache](https://mustache.github.io/)
templating system. It receives [the Story object returned from the Clubhouse API](https://clubhouse.io/api/rest/v3/#Story). Note that you may want to use the
templating system. It receives [the Story object returned from the Shortcut API](https://clubhouse.io/api/rest/v3/#Story). Note that you may want to use the
triple mustache syntax to disable HTML escaping.

GitHub will automatically process the comment text as [Markdown](https://guides.github.com/features/mastering-markdown/),
so you can use features like links and images if you make your comment
template output valid Markdown, as shown above.

If you don't provide a comment template, this action will use this comment template
by default: `Clubhouse story: {{{ story.app_url }}}`
by default: `Shortcut story: {{{ story.app_url }}}`

## Customizing the Clubhouse Story Title and Body
## Customizing the Shortcut Story Title and Body

You can customize the Clubhouse **title** and **description** when creating stories using the `story-title-template` and `story-description-template`
You can customize the Shortcut **title** and **description** when creating stories using the `story-title-template` and `story-description-template`
variables, like this:

```yaml
- uses: singingwolfboy/[email protected]
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
clubhouse-token: ${{ secrets.CLUBHOUSE_TOKEN }}
clubhouse-token: ${{ secrets.SHORTCUT_TOKEN }}
project-name: Engineering
opened-state-name: Started
merged-state-name: Done
Expand All @@ -108,29 +108,29 @@ variables, like this:
```

The story title and body templates are processed using the [Mustache](https://mustache.github.io/)
templating system. It receives [the Payload object returned from the GitHub API](https://docs.github.com/en/free-pro-team@latest/developers/webhooks-and-events/webhook-events-and-payloads#pull_request). Note that you may want to use the triple mustache syntax to disable HTML escaping. Also Clubhouse supports full Markdown formatting, emojis, and @ mentions. Feel free to use them to your heart's desire. :heart_eyes_cat:
templating system. It receives [the Payload object returned from the GitHub API](https://docs.github.com/en/free-pro-team@latest/developers/webhooks-and-events/webhook-events-and-payloads#pull_request). Note that you may want to use the triple mustache syntax to disable HTML escaping. Also Shortcut supports full Markdown formatting, emojis, and @ mentions. Feel free to use them to your heart's desire. :heart_eyes_cat:

If you don't provide a title or body template, this action will simply use the Pull Request Title (`{{{ payload.pull_request.title }}}`) and Pull Request Body (`{{{ payload.pull_request.body }}}`) by default.

## User Map

This Action does its best to automatically assign the created Clubhouse story
This Action does its best to automatically assign the created Shortcut story
to the person who created the GitHub pull request. However, due to limitations
of the GitHub API and the Clubhouse API, this will only work automatically
when the GitHub user and the Clubhouse user share the same _primary_ email
of the GitHub API and the Shortcut API, this will only work automatically
when the GitHub user and the Shortcut user share the same _primary_ email
address. Even though both services allow you to add multiple secondary email
addresses, only the _primary_ email address is exposed in the API.

As a workaround, you can maintain a user map, which teaches this Action how to
map GitHub users to Clubhouse users. The user map should be passed in the
map GitHub users to Shortcut users. The user map should be passed in the
`with` section, and due to the limitations of GitHub Actions, must be a JSON
formatted string. Here's an example:

```yaml
- uses: singingwolfboy/[email protected]
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
clubhouse-token: ${{ secrets.CLUBHOUSE_TOKEN }}
clubhouse-token: ${{ secrets.SHORTCUT_TOKEN }}
project-name: Engineering
user-map: |
{
Expand All @@ -140,13 +140,13 @@ formatted string. Here's an example:
```

The keys of this JSON object must be GitHub usernames, while the values
must be Clubhouse UUIDs that identify members. Unfortunately, these UUIDs
are not exposed on the Clubhouse website; the best way to look them up is to
[go to the User Directory for your Clubhouse workspace](https://app.clubhouse.io/settings/users),
must be Shortcut UUIDs that identify members. Unfortunately, these UUIDs
are not exposed on the Shortcut website; the best way to look them up is to
[go to the User Directory for your Shortcut workspace](https://app.clubhouse.io/settings/users),
open the Developer Tools in your browser, find the API request for
`https://app.clubhouse.io/backend/api/private/members`,
and examine the API response to find the `id` for each user.
Note that Clubhouse makes a distinction between a `User` and a `Member`:
Note that Shortcut makes a distinction between a `User` and a `Member`:
you need to look up the UUID for the `Member` object.

## Ignored Users
Expand All @@ -158,7 +158,7 @@ Multiple users should be separated by commas.
- uses: singingwolfboy/[email protected]
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
clubhouse-token: ${{ secrets.CLUBHOUSE_TOKEN }}
clubhouse-token: ${{ secrets.SHORTCUT_TOKEN }}
project-name: Engineering
ignored-users: hubot, dependabot
```
Expand All @@ -172,23 +172,23 @@ Multiple users should be separated by commas.
- uses: singingwolfboy/[email protected]
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
clubhouse-token: ${{ secrets.CLUBHOUSE_TOKEN }}
clubhouse-token: ${{ secrets.SHORTCUT_TOKEN }}
project-name: Engineering
only-users: dependabot
```

## Iteration Support

Clubhouse supports the concept of [iterations](https://help.clubhouse.io/hc/en-us/articles/360028953452-Iterations-Overview)
Shortcut supports the concept of [iterations](https://help.clubhouse.io/hc/en-us/articles/360028953452-Iterations-Overview)
-- time-boxed periods of development for stories. You can configure this Action
to automatically assign the Clubhouse stories it creates to Clubhouse iterations,
using GitHub labels and Clubhouse groups to identify the correct iteration to use.
to automatically assign the Shortcut stories it creates to Shortcut iterations,
using GitHub labels and Shortcut groups to identify the correct iteration to use.

In order to use this feature, this Action makes a few assumptions about
the way you use Clubhouse and GitHub:
the way you use Shortcut and GitHub:

- We assume that each team has an associated [Clubhouse group](https://help.clubhouse.io/hc/en-us/articles/360039328751-Groups-Group-Management),
and that Clubhouse iterations are associated with this group.
- We assume that each team has an associated [Shortcut group](https://help.clubhouse.io/hc/en-us/articles/360039328751-Groups-Group-Management),
and that Shortcut iterations are associated with this group.
- We assume that the correct iteration to use is the _most recent_
in-progress iteration for the group, as determined by the "last updated" time.
(However, you may exclude specific iterations by name.)
Expand All @@ -215,13 +215,13 @@ on:
```

Next, provide a JSON-formatted string to the `label-iteration-group-map` input.
This is used to map GitHub labels to Clubhouse groups. Here is an example:
This is used to map GitHub labels to Shortcut groups. Here is an example:

```yaml
- uses: singingwolfboy/[email protected]
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
clubhouse-token: ${{ secrets.CLUBHOUSE_TOKEN }}
clubhouse-token: ${{ secrets.SHORTCUT_TOKEN }}
project-name: Engineering
label-iteration-group-map: |
{
Expand All @@ -236,6 +236,6 @@ This is used to map GitHub labels to Clubhouse groups. Here is an example:
```

In this example, "Team Octocat" and "Unicorns" are labels on GitHub.
The "groupId" refers to the ID of the Clubhouse group that are associated
The "groupId" refers to the ID of the Shortcut group that are associated
with these respective teams. The "excludeName" key is optional;
if provided, it is used to exclude specific iterations from consideration.
Loading