Skip to content

Docs: Add docs on private repositories #35

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
natalialuzuriaga merged 2 commits into from
Aug 22, 2025
Merged

Docs: Add docs on private repositories #35

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8101678
Updated procedures doc
natalialuzuriaga Aug 21, 2025
f04d61e
Changed formatting
natalialuzuriaga Aug 21, 2025
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
42 changes: 32 additions & 10 deletions docs/procedures.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,25 +4,28 @@ The CMS Open Source Program Office developed various tools that can automate det

> **Learn more about our SHARE IT Act tools**: https://dsacms.github.io/share-it-act-lp/

## Creating a code.json file
**Procedures for Project Teams**:
[Creating a code.json file in your repository](#creating-a-codejson-file-in-your-repository)
- [code.json generator form site](#using-form-site)
- [automated-codejson-generator GitHub Action](#using-automated-codejson-generator)
- [repo-scaffolder](#using-repo-scaffolder)

### Using repo-scaffolder

[repo-scaffolder](https://github.com/DSACMS/repo-scaffolder) is a tool for creating repositories that adhere to repository hygiene standards. It provides file templates detailing project information, contributing guidance, maintainer roles, community involvement, and **project metadata**.
***Procedures for Agencies**:
[Generate an agency-index.json file for submission](#generate-an-agency-indexjson-file-for-agencies)
- [codejson-index-generator](#using-codejson-index-generator)

For repositories created using repo-scaffolder, the tool can assist with adding code.json to the repository. Navigate to your project's `.github` directory and run the following cookiecutter command. You will be asked questions about the project in order to collect and store this metadata in code.json.

```
cookiecutter . --directory=codejson
```

For more information on repo-scaffolder, check out the [documentation](https://github.com/DSACMS/repo-scaffolder?tab=readme-ov-file#metadata-collection-using-codejson).
## Creating a code.json file in your repository

### Using form site
*This method works best for all repositories on all platforms.*

Users can fill out a web form that creates a code.json file to be uploaded to a project's source code repository: https://dsacms.github.io/codejson-generator.



### Using automated-codejson-generator
*This method works best for repositories hosted on GitHub with GitHub Actions enabled.*

The [automated-codejson-generator](https://github.com/DSACMS/automated-codejson-generator) is a GitHub Action that automatically generates and maintains code.json files for federal open source repositories. It ensures schema consistency and automates metadata calculations, including:

Expand All @@ -31,6 +34,19 @@ The [automated-codejson-generator](https://github.com/DSACMS/automated-codejson-
- Repository information
- Timestamps

### Using repo-scaffolder
*This method is most effective when GitHub Actions are unavailable, allowing cookiecutter to be installed locally with Python.*

[repo-scaffolder](https://github.com/DSACMS/repo-scaffolder) is a tool for creating repositories that adhere to repository hygiene standards. It provides file templates detailing project information, contributing guidance, maintainer roles, community involvement, and **project metadata**.

For repositories created using repo-scaffolder, the tool can assist with adding code.json to the repository. Navigate to your project's `.github` directory and run the following cookiecutter command. You will be asked questions about the project in order to collect and store this metadata in code.json.

```
cookiecutter . --directory=codejson
```

For more information on repo-scaffolder, check out the [documentation](https://github.com/DSACMS/repo-scaffolder?tab=readme-ov-file#metadata-collection-using-codejson).

#### Setting up the GitHub Action

To use the automated-codejson-generator in your repository, create a workflow file with the following configuration:
Expand Down Expand Up @@ -74,10 +90,16 @@ jobs:

This action will create a pull request to add or update a compliant code.json file in your repository.

## Generate an agency-index.json file for agencies

### Using codejson-index-generator

The [codejson-index-generator](https://github.com/DSACMS/codejson-index-generator) is a Python-based tool that helps federal agencies compile and maintain their code.json files for code.gov compliance. It scans specified GitHub organizations, finds repositories containing code.json files, and combines them into a single indexed file.

The tool can be run using the [index-generator-website](https://dsacms.github.io/index-generator-website/).

Alternatively, follow the instructions below to run locally.

#### Prerequisites

- Python 3.x
Expand Down
Loading