# github-sync

**Repository Path**: Sigstore/github-sync

## Basic Information

- **Project Name**: github-sync
- **Description**: Pulumi GitHub Sync for sigstore
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2023-09-27
- **Last Updated**: 2025-06-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Sigstore Github Sync

This projects uses Pulumi and the Pulumi's GitHub provider to create/update Users, Teams, Collaborators and Repositories in GitHub for the Sigstore Organization.
We have a [Pulumi's Open Source account](https://www.pulumi.com/pricing/open-source-free-tier/), thanks for [Pulumi](https://www.pulumi.com/)!

## How to use

1. Open a Pull Request to add/change an Org Member, team, collaborator or repository in the directory `github-data` in the [sigstore/community](https://github.com/sigstore/community) repository.

Note:
  - `github-data/bots.yaml` contains the bot users for the Sigstore Organization
  - `github-data/users.yaml` contains all the Sigstore Org Members
  - `github-data/repositories.yaml` contains all public/private repositories for Sigstore Organization (not included archived and forks).
  - `github-data/teams.yaml` contains all teams.

2. Review the CI to validate if the actions is the one that are expected.
3. After the Pull Request is reviewed and merged the post pipeline will run to run the actions.


## Add a new user

To add a new user to be part of the GitHub Org you should edit the file `github-data/users.yaml`
and add a new entry following the example

```yaml
- username: a-new-user
  role: member # most of the time the role will be member, but also can be admin
  teams:
    - name: cosign-codeowners
      role: member # Must be one of `member` or `maintainer`. Defaults to `member`.
```

- You can check the teams available in `github-data/teams.yaml`, if the user does not need to be in a team just remove the section.
- The role should be `member` in some special cases some users will be `admin`

If we need to add a new Bot user add the similar but in the file `github-data/bots.yaml`

## Add a new team

To add a new team you should edit the file `github-data/users.yaml`
and add a new entry following the example

```yaml
- name: my-new-team
  privacy: closed
  description: Optional description
```

## Add a new repository or update existing ones

To add a new repository you should edit the file `github-data/repositories.yaml``

example:

```yaml
- name: My-RepoName
  owner: sigstore
  description: description # optional
  homepageUrl: ""
  allowAutoMerge: true|false # optional
  allowMergeCommit: true|false # optional
  allowRebaseMerge: true|false # optional
  allowSquashMerge: true|false # optional
  archived: true|false # optional
  autoInit: true|false # optional
  deleteBranchOnMerge: true|false # optional
  hasDiscussions: true|false # optional
  hasDownloads: true|false # optional
  hasIssues: true|false # optional
  hasProjects: true|false # optional
  hasWiki: true|false # optional
  vulnerabilityAlerts: true|false # optional
  visibility: public|private
  licenseTemplate: ""
  topics: []
  collaborators: []
    # - username: sigstore-bot
    #   permission: push # Must be one of `pull`, `push`, `maintain`, `triage` or `admin` for organization-owned repositories.
  teams:
    - name: Core Team
      id: 4563391
      permission: push # Must be one of `pull`, `triage`, `push`, `maintain`, or `admin`. Defaults to `pull`.
```

If you need to configure the GitHub Pages you can add the following definition

```yaml
pages:
  cname: custom cname opcional
  branch: gh-pages
  path: /docs
```

- if path is not set it will default to `/`
- if you set a cname make sure you configure the DNS in aws route53 or similar

If you need to create a new repository that will use a template repository you can set the following

```yaml
isTemplate: true
template:
  owner: my-org
  repository: template
```

To add a branch protection and configure the branch add the following settings:

```yaml
branchesProtection:
  - pattern: main
    enforceAdmins: true|false # optional
    allowsDeletions: true|false # optional
    allowsForcePushes: true|false # optional
    requiredLinearHistory: true|false # optional
    dismissStaleReviews: true|false # optional
    requireSignedCommits: true|false # optional
    requiredApprovingReviewCount: 1
    requireCodeOwnerReviews: true|false # optional
    requireConversationResolution: true|false # optional
    restrictDismissals: true|false # optional
    requireBranchesUpToDate: true|false # optional
    requireLastPushApproval: true|false #optional
    statusChecks:
      - DCO # optional. The name of the status checks that you want to be required for a PR.
    pushRestrictions:
      - MyTeam # optional. Only people, teams, or apps allowed to push will be able to create new branches matching this rule.
    dismissalRestrictions:
      - MyTeam # optional. Specify people, teams, or apps allowed to dismiss pull request reviews.
```

### Remove Users/Collaborators, teams and repositories

All resources, when created, are protected against accidental deletion. If your Pull Request removes a user,
collaborator, team, or repository, the CI will fail, and some Administrators with Pulumi's access will need to run a command
manually to unlock the required resource.

### Reusable GitHub Action

You can use this project to sync your own GitHub Organization. For that you need to follow some steps:

1. Have a repository and add a directory called `github-sync` and inside that one another called `github-data`
2. In the root of `github-sync` will have the Pulumi config `Pulumi.yaml` and `Pulumi.STACK_NAME.yaml`
3. In the directory `github-sync/github-data` will hold the yamls configuration for your GitHub org.
4. Create two Github Actions, one for the Pull Request preview and the other when merge the changes to apply the config.

- Pull request Action:

```yaml
name: GitHub Sync Preview

on:
  pull_request_target:
    branches:
      - main
    paths:
      - 'github-sync/github-data/*.yaml'
      - 'github-sync/Pulumi*.yaml'

jobs:
  preview:
    name: Preview Pulimi changes
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3
      with:
        ref: ${{ github.event.pull_request.head.sha }}
    - uses: sigstore/github-sync@main
      with:
        work_dir: ./github-sync
        config_directory: ./github-sync/github-data
        stack_name: STACK_NAME
        pulumi_access_token: ${{ secrets.PULUMI_TOKEN }}
        pulumi_command: preview
```

- Push to the main branch:

```yaml
name: GitHub Sync Update

on:
  push:
    branches:
      - main
    paths:
      - 'github-sync/github-data/*.yaml'
      - 'github-sync/Pulumi*.yaml'

jobs:
  Update:
    name: Update
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3
    - uses: sigstore/github-sync@main
      with:
        work_dir: ./github-sync
        config_directory: ./github-sync/github-data
        stack_name: STACK_NAME
        pulumi_access_token: ${{ secrets.PULUMI_TOKEN }}
        pulumi_command: up
```