github-action-repo-sync

GitHub Action to detect and sync project metadata to GitHub.

Overview

This action detects metadata from common project configuration files and automatically updates the repository metadata shown in the sidebar on the repository's homepage on GitHub.

It supports setting the description, topic keywords, and homepage URL from a wide variety of project metadata files formats, including package.json, pyproject.toml, codemeta.json files, etc.

This lets you treat your existing metadata as a source of truth for GitHub.

See the underlying metascope project for full details on the range of supported metadata sources.

Getting started

First, ensure you have a fine-grained GitHub personal access token with access to the repository and at least read access to Metadata and read / write access to Administration and Contents. Add the token to your repository under the PERSONAL_ACCESS_TOKEN key or similar.

Example of adding the key with the GitHub CLI:

gh secret set PERSONAL_ACCESS_TOKEN --app actions --body $PERSONAL_ACCESS_TOKEN

Then add the following to your project's .github/workflows directory:

name: Set GitHub Metadata
on:
  push:
    branches: [main]
  workflow_dispatch: {}

permissions:
  contents: read

jobs:
  build:
    name: Set GitHub Metadata
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false

      - name: Sync Package info to GitHub
        uses: kitschpatrol/github-action-repo-sync@v5
        with:
          TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }}

The next time you commit to main, the action will run and update the repository metadata (if possible).

Overriding discovered metadata

Usually, the point of this action is to leverage your existing project metadata (e.g. package.json), but maybe you have a repo with an atypical structure.

To handle such cases, the action checks for a simple metadata.json (or .yaml) file in the repository root, which can capture the minimal metadata required to populate a GitHub project's repository page's description, homepage, and topics.

The file requires three keys, description, homepage, and keywords. A valid metadata.json might look like:

{
  "description": "GitHub Action to detect and sync project metadata to GitHub.",
  "homepage": "https://example.com",
  "keywords": ["github-action", "action", "repo", "project", "metadata"]
}

If a metadata.json file is present, it will override other project metadata sources like package.json.

Homepage validation

Note that if the discovered homepage value is identical to the repository's GitHub homepage URL, then it is not set in the GitHub repository metadata. This prevents cluttering your GitHub repository homepage with a pointless link to itself.

Maintainers

kitschpatrol

Acknowledgments

Thanks to Kevin Brashears for the original shell docker / implementation.

License

MIT © Eric Mika