How to use the command "github-label-sync" (with examples)

Github-label-sync is a powerful command-line tool that allows users to synchronize labels on their GitHub repositories. It provides various features like syncing labels using a local labels.json file, performing a dry run, keeping labels that aren’t in labels.json, and using a specific labels JSON file. In this article, we will explore different use cases of the github-label-sync command and provide detailed code examples, motivations, explanations, and example outputs for each use case.

1: Synchronizing Labels Using a Local labels.json File

github-label-sync --access-token token repository_name

Motivation

Synchronizing labels using a local labels.json file is a common use case when you have a predefined set of labels that you want to apply to your GitHub repository. By using github-label-sync, you can easily sync these labels in one command.

Explanation

• --access-token: This argument is used to specify the GitHub access token required to authenticate the command.
• repository_name: This argument represents the name of the GitHub repository.

Example Output

Labels synchronized successfully.

2: Synchronizing Labels Using a Specific Labels JSON File

github-label-sync --access-token token --labels url|path/to/json_file repository_name

Motivation

In some cases, you may want to synchronize labels using a specific JSON file different from the local labels.json file. This could be useful when you are working with multiple teams or repositories that have different label requirements.

Explanation

• --access-token: Same as in the first use case.
• --labels: This argument is used to specify the URL or path to the JSON file containing the labels you want to sync.
• url|path/to/json_file: You can either provide a URL to the JSON file or the local path to the JSON file.
• repository_name: Same as in the first use case.

Example Output

Labels synchronized successfully.

3: Performing a Dry Run

github-label-sync --access-token token --dry-run repository_name

Motivation

Performing a dry run allows you to preview the changes that will be made to your labels without actually modifying them. This can be helpful to ensure that the synchronization process will produce the desired outcome before making any permanent changes.

Explanation

• --access-token: Same as in the first use case.
• --dry-run: This argument is used to enable the dry run mode.
• repository_name: Same as in the first use case.

Example Output

[Dry Run] Labels to be synchronized:

1. Label 1 (color: #ff0000, description: "First label")
2. Label 2 (color: #00ff00, description: "Second label")
3. Label 3 (color: #0000ff, description: "Third label")

4: Keeping Labels That Aren’t in labels.json

github-label-sync --access-token token --allow-added-labels repository_name

Motivation

By default, github-label-sync removes any labels from the repository that are not present in the labels.json file. However, in some cases, you may want to retain these labels. Using the --allow-added-labels argument allows you to achieve this.

Explanation

• --access-token: Same as in the first use case.
• --allow-added-labels: This argument is used to specify that any labels not present in the labels.json file should be retained.
• repository_name: Same as in the first use case.

Example Output

Labels synchronized successfully. The labels not present in 'labels.json' are retained.

5: Synchronizing Labels Using GITHUB_ACCESS_TOKEN Environment Variable

github-label-sync repository_name

Motivation

Using the GITHUB_ACCESS_TOKEN environment variable to authenticate the command can be useful when you don’t want to specify the access token explicitly in the command itself. It provides a more secure way to authenticate since environment variables can be protected and encrypted.

Explanation

• repository_name: Same as in the first use case.

Example Output

Labels synchronized successfully.

Conclusion

In this article, we explored different use cases of the github-label-sync command for synchronizing GitHub labels. We provided detailed code examples, motivations, explanations, and example outputs for each use case. By leveraging the power of github-label-sync, users can easily sync labels on their GitHub repositories, ensuring consistency and clarity in issue tracking and management.