Skip to content

Remove README content for actions-sync tool #183

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

Open
azariahporras8686-eng wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Remove README content for actions-sync tool #183

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
166 changes: 0 additions & 166 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,167 +1 @@
# Actions Sync

<p align="center">
<img src="docs/arrow.png">
</p>

This is a standalone Go tool to allow you to sync from [GitHub](https://www.github.com) to a [GitHub Enterprise instance](https://github.com/enterprise). GitHub Enterprise is referred to as `GHES` throughout this document.

* Current status: **ready for production use**
* Download from: [releases page](https://github.com/actions/actions-sync/releases/)
* Build status: ![Actions Sync Status](https://github.com/actions/actions-sync/workflows/CI/badge.svg)

It is designed to work when:
* The GitHub Enterprise instance is separate from the rest of the internet.
* The GitHub Enterprise instance is connected to the rest of the internet.

### Note

Thank you for your interest in this GitHub action, however, right now we are not taking contributions.

We continue to focus our resources on strategic areas that help our customers be successful while making developers' lives easier. While GitHub Actions remains a key part of this vision, we are allocating resources towards other areas of Actions and are not taking contributions to this repository at this time. The GitHub public roadmap is the best place to follow along for any updates on features we’re working on and what stage they’re in.

We are taking the following steps to better direct requests related to GitHub Actions, including:

1. We will be directing questions and support requests to our [Community Discussions area](https://github.com/orgs/community/discussions/categories/actions)

2. High Priority bugs can be reported through Community Discussions or you can report these to our support team https://support.github.com/contact/bug-report.

3. Security Issues should be handled as per our [security.md](security.md)

We will still provide security updates for this project and fix major breaking changes during this time.

You are welcome to still raise bugs in this repo.

## Connected instances

When there are machines which have access to both the public internet and the GHES instance run `actions-sync sync`.

**Command:**

`actions-sync sync`

**Arguments:**

- `cache-dir` _(required)_
The directory in which to cache repositories as they are synced. This speeds up re-syncing.
- `destination-url` _(required)_
The URL of the GHES instance to sync repositories onto.
- `destination-token` _(required)_
A personal access token to authenticate against the GHES instance when uploading repositories. See [Destination token scopes](#destination-token-scopes) below.
- `source-token` _(optional)_
A token used to authenticate against the source when pulling private repositories. For a personal access token, the `repo` scope (read access to the source repositories) is sufficient. For a GitHub App installation token (`ghs_*`), the installation needs read access to the source repositories' contents; App tokens use installation permissions, not OAuth scopes. Must be used with an `https://` `source-url`.
- `default-branch-only` _(optional)_
Only synchronize the single default branch rather than the default behaviour of syncing all branches. Tags are always synced. The default branch is always refreshed, including on subsequent runs into an existing `cache-dir`, but no other branches are pulled. If a repository was previously cached without this flag, the extra branches already in the `cache-dir` are left as-is (they are neither updated nor removed).
- `repo-name` _(optional)_
A single repository to be synced. In the format of `owner/repo`. Optionally if you wish the repository to be named different on your GHES instance you can provide an alias in the format: `upstream_owner/upstream_repo:destination_owner/destination_repo`
- `repo-name-list` _(optional)_
A comma-separated list of repositories to be synced. Each entry follows the format of `repo-name`.
- `repo-name-list-file` _(optional)_
A path to a file containing a newline separated list of repositories to be synced. Each entry follows the format of `repo-name`.
- `actions-admin-user` _(optional)_
The name of the Actions admin user, which will be used for updating the chosen action. To use the default user, pass `actions-admin`. If not set, the impersonation is disabled. Note that `site_admin` scope is required in the token for the impersonation to work.
- `github-app-auth` _(optional)_
Authenticate using a GitHub App installation token (`ghs_*`) instead of a personal access token. App tokens have no user context, so the user API call is skipped and repositories are created under the owner taken from the destination repo name, which must be an organization the App is installed on (installation tokens cannot create user-owned repositories). See [GitHub App authentication](#github-app-authentication) below.
- `batch-size` _(optional)_
Number of refs to push in each batch. Default is 0 (no batching). Use a value like 100 if pushing fails for large repositories with many branches and tags.

**Example Usage:**

```
actions-sync sync \
--cache-dir "/tmp/cache" \
--destination-token "token" \
--destination-url "https://www.example.com" \
--repo-name actions/setup-node
```

## Not connected instances

When no machine has access to both the public internet and the GHES instance:

1. `actions-sync pull` on a machine with public internet access
2. copy the provided `cache-dir` to a machine with access to the GHES instance
3. run `actions-sync push` on the machine with access to the GHES instance

**Command:**

`actions-sync pull`

**Arguments:**

- `cache-dir` _(required)_
The directory to cache the pulled repositories into.
- `source-token` _(optional)_
A token used to authenticate against the source when pulling private repositories. For a personal access token, the `repo` scope (read access to the source repositories) is sufficient. For a GitHub App installation token (`ghs_*`), the installation needs read access to the source repositories' contents; App tokens use installation permissions, not OAuth scopes. Must be used with an `https://` `source-url`.
- `default-branch-only` _(optional)_
Only synchronize the single default branch rather than the default behaviour of syncing all branches. Tags are always synced. The default branch is always refreshed, including on subsequent runs into an existing `cache-dir`, but no other branches are pulled. If a repository was previously cached without this flag, the extra branches already in the `cache-dir` are left as-is (they are neither updated nor removed).
- `repo-name` _(optional)_
A single repository to be synced. In the format of `owner/repo`. Optionally if you wish the repository to be named different on your GHES instance you can provide an alias in the format: `upstream_owner/upstream_repo:destination_owner/destination_repo`
- `repo-name-list` _(optional)_
A comma-separated list of repositories to be synced. Each entry follows the format of `repo-name`.
- `repo-name-list-file` _(optional)_
A path to a file containing a newline separated list of repositories to be synced. Each entry follows the format of `repo-name`.

**Example Usage:**

```
bin/actions-sync pull \
--cache-dir "/tmp/cache" \
--repo-name actions/setup-node
```

**Command:**

`actions-sync push`

**Arguments:**

- `cache-dir` _(required)_
The directory containing the repositories fetched using the `pull` command.
- `destination-url` _(required)_
The URL of the GHES instance to sync repositories onto.
- `destination-token` _(required)_
A personal access token to authenticate against the GHES instance when uploading repositories. See [Destination token scopes](#destination-token-scopes) below.
- `repo-name`, `repo-name-list` or `repo-name-list-file` _(optional)_
Limit push to specific repositories in the cache directory.
- `actions-admin-user` _(optional)_
The name of the Actions admin user, which will be used for updating the chosen action. To use the default user, pass `actions-admin`. If not set, the impersonation is disabled. Note that `site_admin` scope is required in the token for the impersonation to work.
- `github-app-auth` _(optional)_
Authenticate using a GitHub App installation token (`ghs_*`) instead of a personal access token. App tokens have no user context, so the user API call is skipped and repositories are created under the owner taken from the destination repo name, which must be an organization the App is installed on (installation tokens cannot create user-owned repositories). See [GitHub App authentication](#github-app-authentication) below.
- `batch-size` _(optional)_
Number of refs to push in each batch. Default is 0 (no batching). Use a value like 100 if pushing fails for large repositories with many branches and tags.

**Example Usage:**

```
bin/actions-sync push \
--cache-dir "/tmp/cache" \
--destination-token "token" \
--destination-url "https://www.example.com"
```

## Destination token scopes

When creating a personal access token include the `repo` and `workflow` scopes. Include the `site_admin` scope (optional) if you want organizations to be created as necessary or you want to use the impersonation logic for the `push` or `sync` commands.

## GitHub App authentication

Instead of a personal access token you can authenticate `push`/`sync` using a GitHub App installation token (`ghs_*`). This avoids long-lived PATs and aligns with enterprise security practices.

1. Create a GitHub App on the destination GHES instance and install it on the target organization(s). The destination owner must be an organization: installation tokens cannot create user-owned repositories (`POST /user/repos` requires user context that App tokens lack), so a user-account installation will not work.
2. Grant the App these repository permissions: `Administration: Read & write` (to create repositories), `Contents: Read & write` and `Metadata: Read-only`. Add `Workflows: Read & write` if the synced repositories contain workflow files.
3. Generate an installation access token (`ghs_*`) for the installation.
4. Pass the token as `--destination-token` together with the `--github-app-auth` flag:

```
actions-sync push \
--cache-dir "/tmp/cache" \
--destination-token "ghs_xxxxxxxxxxxxxxxxxxxx" \
--destination-url "https://www.example.com" \
--github-app-auth
```

Notes:

- App installation tokens have no user context, so `--github-app-auth` skips the `GET /user` call and creates repositories under the owner taken from the destination repo name (`owner/repo`) via `POST /orgs/{owner}/repos`. The owner must therefore be an organization the App is installed on; user-owned destinations are not supported because installation tokens cannot create user-owned repositories.
- Organization auto-creation and user-impersonation (`--actions-admin-user`) rely on user/site-admin context and are not used with App auth.