Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/EndBug/label-sync

:octocat: An action that allows you to sync labels from a repository or a config file
https://github.com/EndBug/label-sync

actions ci github hacktoberfest labels repository sync utility workflow

Last synced: 3 months ago
JSON representation

:octocat: An action that allows you to sync labels from a repository or a config file

Host: GitHub
URL: https://github.com/EndBug/label-sync
Owner: EndBug
License: mit
Created: 2020-10-08T06:27:45.000Z (about 4 years ago)
Default Branch: main
Last Pushed: 2024-07-03T11:05:43.000Z (4 months ago)
Last Synced: 2024-07-18T23:24:58.581Z (4 months ago)
Topics: actions, ci, github, hacktoberfest, labels, repository, sync, utility, workflow
Language: TypeScript
Homepage:
Size: 2.84 MB
Stars: 22
Watchers: 1
Forks: 12
Open Issues: 7
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE

Awesome Lists containing this project

README

# label-sync
[![All Contributors](https://img.shields.io/github/all-contributors/EndBug/label-sync)](#contributors-)

An action that allows you to sync labels from a repository or a config file.

### Example workflow:

```yaml
name: Sync labels
on:
# You can run this with every type of event, but it's better to run it only when you actually need it.
workflow_dispatch:

permissions:
issues: write

jobs:
labels:
runs-on: ubuntu-latest

steps:
- uses: actions/checkout@v4
with:
sparse-checkout: .github/labels.yml

- uses: EndBug/label-sync@v2
with:
# If you want to use a config file, you can put its path or URL here, multiple files are also allowed (more info in the paragraphs below)
config-file: .github/labels.yml
# as URL:
config-file: https://raw.githubusercontent.com/EndBug/labels/main/labels.yml
# as multiple:
config-file: |
https://raw.githubusercontent.com/EndBug/labels/main/labels.yml
.github/labels.yml

# If you want to use a source repo, you can put is name here (only the owner/repo format is accepted)
source-repo: owner/repo

# If you're using a private source repo or a URL that needs an 'Authorization' header, you'll need to add a custom token for the action to read it
request-token: ${{ secrets.YOUR_OWN_SECRET }}

# If you want to delete any additional label, set this to true
delete-other-labels: false

# If you want the action just to show you the preview of the changes, without actually editing the labels, set this to true
dry-run: true

# You can change the token used to change the labels, this is the default one
token: ${{ secrets.GITHUB_TOKEN }}
```

This is only a sample workflow to illustrate all the options: if you want to see an actual workflow you can check out the one in this repo [here](.github/workflows/labels.yml).

### Config files

If you want to use a config file you can create your own following the instructions below.

If you want to start off by copying the labels from another repository, you can use my [`EndBug/export-label-config` action](https://github.com/EndBug/export-label-config), that will generate one for you.

How to create a config file:

- Create a JSON or YAML file, with one of these extensions: `.json`, `.yaml`, `.yml`.
- Every label should be an array element: add some square brackets `[]` if you need to.
- Every element of the array should be an object with the following properties:
- `name` - The name of the label.
- `color` - The color of the label, with or without a leading `#`.
- `description` - [optional] The description of the label ([max 100 characters](https://docs.github.com/en/rest/issues/labels?apiVersion=2022-11-28#create-a-label)).
- `aliases` - [optional] An array containing the "aliases" of the label. If an existing label's name is an alias that label will be edited to match your config: this way you don't loose issues and PRs that have been labeled previously.

This is how it would end up looking:

```yaml
- name: A label
color: '000000'

- name: Another label
color: '111111'
description: A very inspiring description

- name: Yet another label
color: '222222'
aliases: ['first', 'second', 'third']
```

```json
[
{
"name": "A label",
"color": "000000"
},
{
"name": "Another label",
"color": "111111",
"description": "A very inspiring description"
},
{
"name": "Yet another label",
"color": "222222",
"aliases": ["first", "second", "third"]
}
]
```

Note that `color` may be specified in either `000000` or `'#000000'` format. Mind the quotes when using yaml.

If you want to see an actual config file, you can check out the one in this repo [here](https://github.com/EndBug/labels/blob/main/labels.yml).

This action can either read a local file or fetch it from a custom URL.
If you want to use a URL make sure that the data field of the response contains JSON or YAML text that follows the structure above.

An example of how you may want to use a URL instead of a local file is if you want to use a config file that is located in a GitHub repo, without having to copy it to your own.
You can use the "raw" link that GitHub provides for the file:

```yaml
- uses: EndBug/label-sync@v2
with:
# This is just an example, but any valid URL can be used
config-file: 'https://raw.githubusercontent.com/EndBug/labels/main/labels.yml'
```

You can also specify several config files (e.g. sync a set of "global" labels as well as a set of "local" labels):

```yaml
- uses: EndBug/label-sync@v2
with:
config-file: |
https://raw.githubusercontent.com/EndBug/labels/main/labels.yml
.github/labels.yml
```

This is different than using the `source-repo` option, since this also allows you to use aliases, if the config file has any. If you use the `source-repo` option the action will only copy over the missing labels and update colors, without updating or deleting anything else.

If the URL you're using needs an `Authorization` header (like if, for example, you're fetching it from a private repo), you can put its value in the `request-token` input:

```yaml
- uses: EndBug/label-sync@v2
with:
config-file: 'https://raw.githubusercontent.com/User/repo-name/path/to/labels.yml'
# Remember not to put PATs in files, use GitHub secrets instead
request-token: ${{ secrets.YOUR_CUSTOM_PAT }}
```

The `request-token` input can also be used with a `source-repo`, if that repo is private.

If your URL needs a more elaborate request, it's better if you perform it separately and save its output to a local file. You can then run the action using the local config file you just created.

## Contributors ✨

Thanks go to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

_{Federico Grandi}
💻

_K3rnelPan1c
💻

_danielwerg
📖

_{Ken Odegard}
💻

_{Adam Snyder}
💻

_{Salvador real}
💻

_{Simon Lepel}
💻

_{Carlos Rodríguez Hernández}
💻

_Marco
🐛

_{Andrew Vaughan}
📖

_{Reece Hart}
🚧

This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!