{"id":25970576,"url":"https://github.com/xebis/github-organization-as-code","last_synced_at":"2025-09-04T19:06:32.004Z","repository":{"id":279671760,"uuid":"939013841","full_name":"xebis/github-organization-as-code","owner":"xebis","description":"Manage your GitHub organization's repositories using GitOps principles with a YAML-based configuration, GitHub Actions with reusable workflows, AWS S3 for storage, and GitHub App integration.","archived":false,"fork":false,"pushed_at":"2025-07-01T21:38:14.000Z","size":20,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-01T22:28:44.014Z","etag":null,"topics":["github","github-app","github-management","github-organization","github-repositories","github-workflows","gitops","iac","terraform","terraform-backend-s3","terraform-github","terraform-github-provider","yaml-configuration"],"latest_commit_sha":null,"homepage":"","language":"HCL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xebis.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-02-25T21:15:46.000Z","updated_at":"2025-07-01T21:38:16.000Z","dependencies_parsed_at":"2025-04-27T07:29:25.894Z","dependency_job_id":null,"html_url":"https://github.com/xebis/github-organization-as-code","commit_stats":null,"previous_names":["xebis/github-organization-as-code"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/xebis/github-organization-as-code","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xebis%2Fgithub-organization-as-code","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xebis%2Fgithub-organization-as-code/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xebis%2Fgithub-organization-as-code/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xebis%2Fgithub-organization-as-code/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xebis","download_url":"https://codeload.github.com/xebis/github-organization-as-code/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xebis%2Fgithub-organization-as-code/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273657130,"owners_count":25145018,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-04T02:00:08.968Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["github","github-app","github-management","github-organization","github-repositories","github-workflows","gitops","iac","terraform","terraform-backend-s3","terraform-github","terraform-github-provider","yaml-configuration"],"created_at":"2025-03-04T23:17:51.161Z","updated_at":"2025-09-04T19:06:31.994Z","avatar_url":"https://github.com/xebis.png","language":"HCL","readme":"# GitHub Organization as Code\n\nManage your GitHub organization's repositories using GitOps principles with a YAML-based configuration, GitHub Actions with reusable workflows, AWS S3 for storage, and GitHub App integration.\n\n## Features\n\n- **Automated Repository Management** - Define repositories, and repository properties using simple YAML file.\n- **GitOps Workflow** - Manage configurations via pull requests and automate updates using GitHub Actions.\n- **Terraform** - Uses Terraform under the hood to apply changes efficiently.\n- **Terraform State Management** - Stores Terraform state securely in AWS S3.\n- **GitHub App Integration** - Uses a GitHub App for authentication and API interactions.\n\n### Fun Fact\n\nThis repository was automatically created and is continuously managed using the very code inside it!\n\n## Installation and Configuration\n\n- Configure an AWS S3 bucket to store Terraform state files.\n- Set up a GitHub App and its installation to handle authentication and authorization for your GitHub Organization.\n- Implement GitOps by setting up a GitHub repository with:\n  - YAML-based configuration\n  - GitHub workflows\n  - Repository variables and secrets\n\n\u003e [!caution]\n\u003e The GitHub App PEM file, S3 API credentials, Terraform state, GitHub repository secrets, and configuration code are key security elements.\n\n### Set Up AWS S3 Bucket\n\nSet up an AWS S3 bucket or a compatible storage service.\n\n\u003e [!important]\n\u003e Ensure you have the following details ready:\n\u003e\n\u003e - Bucket Name\n\u003e - Access Key ID\n\u003e - Secret Access Key\n\u003e - Region\n\u003e - S3 Endpoint URL (only required for non-AWS S3-compatible services)\n\n### Set Up GitHub Organizations\n\nCreate a GitHub App:\n\n- GitHub / *Organization* / Settings / Developer Settings / GitHub Apps / **New GitHub App**\n  - Register new GitHub App\n    - GitHub App name: *Your GitHub App name*\n      - Description: *Your GitHub App description*\n    - HomepageURL: *Your GitHub App URL*\n  - Webhook\n    - Active: unchecked\n  - Permissions\n    - Repository permissions\n      - Administration: Read and write\n    - Organization permissions\n      - Administration: Read and write\n    - Where can this GitHub App be installed?:  \n      Only on this account *(for installations only in the current organization)*  \n      Any account *(for installations in any organization)*\n\nInstall the GitHub App:\n\n- GitHub / *Organization* / Settings / Developer Settings / GitHub Apps / *Your GitHub App name* / Install App\n  - **For each** *owner*\n    - **Install**\n      - for these repositories: All repositories\n      - **Install**\n\nGet the GitHub App credentials:\n\n- GitHub / *Organization* / Settings / Developer Settings / GitHub Apps / *Your GitHub App name* / General / Private keys / **Generate a private key**\n\n\u003e [!important]\n\u003e Ensure you have the following details ready:\n\u003e\n\u003e - GitHub Owner\n\u003e - GitHub App ID\n\u003e - GitHub App Installation ID\n\u003e - GitHub App PEM File\n\n### Set Up GitHub Repository for GitHub Organization Management\n\nCreate GitHub organization YAML configuration file. See [GitHub Organization YAML](#github-organization-yaml) below.\n\nFor example:\n\n```yaml\n---\nrepositories:\n  - name: .github\n    description: The organization profile.\n    topics:\n      - github-organization-profile\n      - github-profile\n      - github-profile-readme\n```\n\nCreate GitHub workflow planning and applying configuration changes to the GitHub Organization:\n\n```yaml\n---\non:\n  push:\n    branches:\n      - main\n  pull_request:\n    branches:\n      - main\n\njobs:\n  call-terraform:\n    uses: xebis/github-organization-as-code/.github/workflows/terraform.yaml@v0\n    with:\n      aws_region: ${{ vars.AWS_REGION }}\n      aws_endpoint_url_s3: ${{ vars.AWS_ENDPOINT_URL_S3 }}\n      gh_owner: ${{ vars.GH_OWNER }}\n      gh_app_id: ${{ vars.GH_APP_ID }}\n      gh_app_installation_id: ${{ vars.GH_APP_INSTALLATION_ID }}\n      path: xebis.yaml\n    secrets:\n      aws_access_key_id: ${{ secrets.AWS_ACCESS_KEY_ID }}\n      aws_secret_access_key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}\n      gh_app_pem_file: ${{ secrets.GH_APP_PEM_FILE }}\n```\n\nSet up GitHub actions, variables and secrets:\n\n- GitHub / *Repository* / Settings\n  - Actions / General\n    - Workflow permissions: Read and write permissions\n  - Secrets and variables / Actions / Actions secrets and variables\n    - Secrets\n      - **New repository secret**\n        - `GH_APP_PEM_FILE` (`GITHUB_APP_PEM_FILE` contents)\n        - `AWS_ACCESS_KEY_ID`\n        - `AWS_SECRET_ACCESS_KEY`\n    - Variables\n      - **New repository variable**\n        - `GH_APP_ID` (`GITHUB_APP_ID`)\n        - `GH_APP_INSTALLATION_ID` (`GITHUB_APP_INSTALLATION_ID`)\n        - `AWS_ENDPOINT_URL_S3`\n        - `AWS_REGION`\n        - `GH_OWNER` (`GITHUB_OWNER`)\n\n## Usage\n\nThe GitHub organization YAML configuration post a Terraform plan as a pull request comment whenever a pull request to the main branch is created or whenever a new commit to the pull request is pushed. Once the pull request is merged into `main`, the plan is applied automatically.\n\n\u003e [!note]\n\u003e The state is stored as JSON object `github/\u003cgithub owner\u003e/terraform.tfstate` in the bucket.\n\n### GitHub Organization YAML\n\nThe example below demonstrates the full range of capabilities available in the organization YAML configuration.\n\n```yaml\n---\norganization:\n  all-repositories: # OPTIONAL\n    # All-repository default properties\n    visibility: public # OPTIONAL, DEFAULT public\n    # All-repository default features\n    has_issues: true # OPTIONAL, DEFAULT false\n    has_discussions: true # OPTIONAL, DEFAULT false\n    has_projects: true # OPTIONAL, DEFAULT false\n    has_wiki: true # OPTIONAL, DEFAULT false\n    # All-repository default settings\n    allow_merge_commit: false # OPTIONAL, DEFAULT true\n    allow_squash_merge: true # OPTIONAL, DEFAULT true\n    allow_rebase_merge: true # OPTIONAL, DEFAULT true\n    allow_auto_merge: true # OPTIONAL, DEFAULT false\n    delete_branch_on_merge: true # OPTIONAL, DEFAULT false\n    # All-repository default rulesets\n    rulesets:\n      - name: \"Main Branch\"\n        target: branch # REQUIRED, VALUES branch or tag\n        enforcement: active # REQUIRED, VALUES disabled or active\n        bypass_actors: # OPTIONAL, DEFAULT empty\n            # Xebis GitHub Semantic Release https://github.com/apps/xebis-github-semantic-release\n          - actor_id: 1527160 # REQUIRED, VALUE The ID of the actor\n            actor_type: Integration # REQUIRED, VALUES RepositoryRole, Team, Integration, OR OrganizationAdmin\n            bypass_mode: always # REQUIRED, VALUES always or pull_request\n        conditions: # OPTIONAL, DEFAULT empty\n          ref_name:\n            include: # OPTIONAL, DEFAULT empty, VALUE array of ref names or patterns to include, SPECIAL VALUES ~ALL and ~DEFAULT_BRANCH also accepted\n              - ~DEFAULT_BRANCH\n            exclude: # OPTIONAL, DEFAULT empty\n        rules:\n          creation: true # OPTIONAL, DEFAULT false\n          update: true # OPTIONAL, DEFAULT false\n          update_allows_fetch_and_merge: false # OPTIONAL, DEFAULT false\n          deletion: true # OPTIONAL, DEFAULT false\n          required_linear_history: true # OPTIONAL, DEFAULT false\n          required_signatures: true # OPTIONAL, DEFAULT false\n          pull_request: # OPTIONAL, DEFAULT empty MEANING does not require a pull request before merging\n            required_approving_review_count: 0 # OPTIONAL, DEFAULT 0\nrepositories:\n  - name: repo-slug\n    # Repository metadata\n    description: Repository description. # OPTIONAL, DEFAULT none\n    homepage_url: http://repo.domain/ # OPTIONAL, DEFAULT none\n    topics: # OPTIONAL, DEFAULT none\n      - github-topic-1\n    # Repository properties\n    visibility: public # OPTIONAL, DEFAULT public\n    is_template: true # OPTIONAL, DEFAULT false\n    # Repository features\n    has_issues: true # OPTIONAL, DEFAULT false\n    has_discussions: true # OPTIONAL, DEFAULT false\n    has_projects: true # OPTIONAL, DEFAULT false\n    has_wiki: true # OPTIONAL, DEFAULT false\n    # Repository settings\n    allow_merge_commit: false # OPTIONAL, DEFAULT true\n    allow_squash_merge: true # OPTIONAL, DEFAULT true\n    allow_rebase_merge: true # OPTIONAL, DEFAULT true\n    allow_auto_merge: true # OPTIONAL, DEFAULT false\n    delete_branch_on_merge: true # OPTIONAL, DEFAULT false\n```\n\nDefaults are usually the same as in the Terraform provider `github` resource `github_repository`, see [Terraform Registry / Providers / integrations / github / resources / github_repository](https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository#argument-reference).\n\n### Local Usage\n\nApply the configuration using Terraform:\n\n```shell\n# Environment variables\nexport AWS_REGION=\u003caws-region\u003e\nexport AWS_ENDPOINT_URL_S3=\u003caws-endpoint-url-s3\u003e # Only for non-AWS S3 compatible APIs\nexport AWS_ACCESS_KEY_ID=\u003caws-access-key-id\u003e\nexport AWS_SECRET_ACCESS_KEY=\u003caws-secret-access-key\u003e\n\nexport GITHUB_OWNER=\u003cowner\u003e\nexport GITHUB_APP_ID=\u003capp-id\u003e\nexport GITHUB_APP_INSTALLATION_ID=\u003capp-installation-id\u003e\nexport GITHUB_APP_PEM_FILE=$(cat \u003capp-private-key.pem\u003e)\n\nexport TF_WORKSPACE=\"$GITHUB_OWNER\"\nexport TF_VAR_path=\"../test.yaml\"\n\n# Terraform\nterraform -chdir=terraform init\nterraform -chdir=terraform plan\nterraform -chdir=terraform apply\n```\n\n## Testing\n\nThis repository is tested using [`test.yaml`](test.yaml) as the configuration file for the [Xebis Test GitHub Organization](https://github.com/xebis-test) settings and repositories.\n\nThe workflow is designed to post a Terraform plan as a pull request comment whenever a pull request to the main branch is created or whenever a new commit to the pull request is pushed. Once the pull request is merged into `main`, the plan is applied automatically.\n\n## Credits and Acknowledgments\n\n- Martin Bružina - Author\n\n## Copyright and Licensing\n\n- MIT License  \n  Copyright © 2025 Martin Bružina\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxebis%2Fgithub-organization-as-code","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxebis%2Fgithub-organization-as-code","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxebis%2Fgithub-organization-as-code/lists"}