Skip to content

Commit

Permalink
docs: Updates to README.md
Browse files Browse the repository at this point in the history 
Fix several markdown lint issues and update instructions for new
`secrets.env` file.
  • Loading branch information
@rcdailey
rcdailey committed Dec 25, 2023
1 parent 7fec8ed commit 58f201e
Showing 1 changed file with 68 additions and 51 deletions.
119 changes: 68 additions & 51 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,76 +2,84 @@

Notify Discord with all commits present in a payload. Customize layout by customizing templates.

## Example Appearance:
## Example Appearance

Use markdown in your commit messages for nice formatting. As an example, here is a link to commit in picture. https://github.com/Sniddl/discord-commits/commit/1e5aedd3f8bae8bb8272289cea173f2258e519e8
Use markdown in your commit messages for nice formatting. As an example, [here is the
commit][commit] in picture.

![Imgur](https://imgur.com/YvLWWGL.jpg)

<hr/>
[commit]: https://github.com/Sniddl/discord-commits/commit/1e5aedd3f8bae8bb8272289cea173f2258e519e8

## Example Usage

```yaml
- name: Discord Commits
uses: Sniddl/[email protected]
with:
webhook: ${{ secrets.DISCORD_WEBHOOK }}
template: 'avatar-with-link'
include-extras: true
uses: Sniddl/[email protected]
with:
webhook: ${{ secrets.DISCORD_WEBHOOK }}
template: 'avatar-with-link'
include-extras: true
```
## Variables inside templates
Global Variable | Description
|---|---|
github | Access all data provided by GitHub such as payloads and commits. For example, the repository name. `{{ github.context.payload.repository.name }}`
env | Access all environment variables. For example, an environment variable called my_data. `{{ env.my_data }}`
commit | Access the data for the current commit. This will apply to ALL commits in the push event. If you do not want multiple commits see other options. Here's an example for commit data `{{ commit.author.name }}`
| Global Variable | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| github | Access all data provided by GitHub such as payloads and commits. For example, the repository name. `{{ github.context.payload.repository.name }}` |
| env | Access all environment variables. For example, an environment variable called my_data. `{{ env.my_data }}` |
| commit | Access the data for the current commit. This will apply to ALL commits in the push event. If you do not want multiple commits see other options. Here's an example for commit data `{{ commit.author.name }}` |

## Required options

Option | Description
|---|---|
webhook | The url for a Discord webhook. Store this as a secret otherwise you may receive unwanted spam in your discord.
| Option | Description |
| ------- | -------------------------------------------------------------------------------------------------------------- |
| webhook | The url for a Discord webhook. Store this as a secret otherwise you may receive unwanted spam in your discord. |

## Essential options

Option | Description
|---|---|
template | The name of a premade template located into the discord-commits/templates folder.
message | The text message that appears on Discord. This would be the equivalent of typing a message.
embed | The template for each embed item. An embed item is shown for every commit message in the push event. There may be multiple commits per push. This can be prevented by enabling **last-commit-only**
| Option | Description |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| template | The name of a premade template located into the discord-commits/templates folder. |
| message | The text message that appears on Discord. This would be the equivalent of typing a message. |
| embed | The template for each embed item. An embed item is shown for every commit message in the push event. There may be multiple commits per push. This can be prevented by enabling **last-commit-only** |

## Other options
Option | Description
|---|---|
include-extras | Boolean - Include extra embeds from templates such as a link to the payload difference.
last-commit-only | Boolean - Only include the last commit.
## Other Options

| Option | Description |
| ---------------- | --------------------------------------------------------------------------------------- |
| include-extras | Boolean - Include extra embeds from templates such as a link to the payload difference. |
| last-commit-only | Boolean - Only include the last commit. |

## Resources
For information on the GitHub context API visit https://docs.github.com/en/actions/learn-github-actions/contexts
For information on the Discord Webhook API visit https://discord.com/developers/docs/resources/webhook

---
- [Github Context API][contextapi]
- [Discord Webhook API][discordapi]

[contextapi]: https://docs.github.com/en/actions/learn-github-actions/contexts
[discordapi]: https://discord.com/developers/docs/resources/webhook

# Predefined templates
## Predefined templates

Here are the defaults for each template. If you want to modify the values, you need to turn the JSON into a string so it can be passed from the action environment to the script. See main.yml for a commented out example.
Here are the defaults for each template. If you want to modify the values, you need to turn the JSON
into a string so it can be passed from the action environment to the script. See main.yml for a
commented out example.

## `plain`

## plain
Returns a message and no embeds

```
```js
{
embed: false,
}
```

## plain-author
## `plain-author`

Returns embeds containing a title and description. Includes the author's name.

```
```js
{
embed: {
title: "{{ commit.title }}",
Expand All @@ -83,10 +91,11 @@ Returns embeds containing a title and description. Includes the author's name.
}
```

## simple-link
## `simple-link`

Returns embeds containing a title and description. The title links to the commit url

```
```js
{
embed: {
title: "{{ commit.title }}",
Expand All @@ -96,10 +105,12 @@ Returns embeds containing a title and description. The title links to the commit
}
```

## author-with-link
Returns embeds containing a title and description. The title links to the commit url. Includes the author's name
## `author-with-link`

```
Returns embeds containing a title and description. The title links to the commit url. Includes the
author's name

```js
embed: {
title: "{{ commit.title }}",
description: "{{ commit.description }}",
Expand All @@ -110,10 +121,12 @@ embed: {
}
```

## avatar-with-link
Returns embeds containing a title and description. The title links to the commit url. Includes author's name and GitHub avatar.
## `avatar-with-link`

```
Returns embeds containing a title and description. The title links to the commit url. Includes
author's name and GitHub avatar.

```js
embed: {
title: "{{ commit.title }}",
description: "{{ commit.description }}",
Expand All @@ -125,15 +138,19 @@ embed: {
}
```

## Testing / Contributing.
## Testing / Contributing

Tests use https://github.com/nektos/act to simulate GitHub Actions locally.
We suggest everyone uses a tool like [nektos/act] to test GitHub actions locally. This is the tool I
use so the directory structure will reflect that. If the following command does not pass, I will not
accept your PR.

1. install act see https://github.com/nektos/act for instructions.
1. `cp .env.example .env.secrets` paste discord commit url into .env.secrets
1. make sure the following command passes.
1. Install act. See [nektos/act] for instructions.
1. `cp secrets.env.example tests/secrets.env`. Open `tests/secrets.env` and paste your discord
webhook url into the value for `DISCORD_WEBHOOK`.
1. From the root of the repo, make sure the following command passes:

```
./tests/deploy/test.sh
```
```sh
./tests/deploy/test.sh
```

[nektos/act]: https://github.com/nektos/act

0 comments on commit 58f201e

Please sign in to comment.