From 5cbe859953511ea515b84b67897326717c750560 Mon Sep 17 00:00:00 2001 From: Chris Gavin Date: Mon, 24 Aug 2020 13:49:19 +0100 Subject: [PATCH] Add a bunch more details on how to use the tool to the readme. --- README.md | 43 +++++- docs/logo.png | Bin 0 -> 2833 bytes docs/logo.svg | 361 ++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 403 insertions(+), 1 deletion(-) create mode 100644 docs/logo.png create mode 100644 docs/logo.svg diff --git a/README.md b/README.md index bfabc38..63d0408 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,43 @@ # CodeQL Action Sync Tool -A tool for syncing the [CodeQL Action](https://github.com/github/codeql-action/) from GitHub.com to GitHub Enterprise Server, including copying the CodeQL bundle. +![Logo](docs/logo.png) + +A tool for syncing the [CodeQL Action](https://github.com/github/codeql-action/) from GitHub.com to GitHub Enterprise Server, including copying the CodeQL bundle. This allows the CodeQL Action to work even if your GitHub Enterprise Server or GitHub Actions runners do not have internet access. + +## Installation +The CodeQL Action sync tool can be downloaded from the [releases page](https://github.com/github/codeql-action-sync-tool/releases/latest/) of this repository. + +## Usage +The sync tool can be used in two different ways. + +If you have a machine that is able to access GitHub.com and the GitHub Enterprise Server instance then simply follow the steps under ["I have a machine that can access both GitHub.com and GitHub Enterprise Server"](#i-have-a-machine-that-can-access-both-githubcom-and-github-enterprise-server). + +If your GitHub Enterprise Server instance is on a completely isolated network where no machines have access to both GitHub.com and GitHub Enterprise Server then follow the steps under ["I don't have a machine that can access both GitHub.com and GitHub Enterprise Server"](#i-dont-have-a-machine-that-can-access-both-githubcom-and-github-enterprise-server) instead. + +### I have a machine that can access both GitHub.com and GitHub Enterprise Server. +From a machine with access to both GitHub.com and GitHub Enterprise Server use the `./codeql-action-sync sync` command to copy the CodeQL Action and bundles. + +**Required Arguments:** +* `--destination-url` - The URL of the GitHub Enterprise Server instance to push the Action to. +* `--destination-token` - A [Personal Access Token](https://docs.github.com/en/enterprise/user/github/authenticating-to-github/creating-a-personal-access-token) for the destination GitHub Enterprise Server instance. The token should be granted at least the `public_repo` scope. If the destination repository is in an organization that does not yet exist, your token will need to have the `site_admin` scope in order to create the organization. The organization can also be created manually or an existing organization used. + +**Optional Arguments:** +* `--cache-dir` - A temporary directory in which to store data downloaded from GitHub.com before it is uploaded to GitHub Enterprise Server. If not specified a directory next to the sync tool will be used. +* `--destination-repository` - The name of the repository in which to create or update the CodeQL Action. If not specified `github/codeql-action` will be used. + +### I don't have a machine that can access both GitHub.com and GitHub Enterprise Server. +From a machine with access to GitHub.com use the `./codeql-action-sync pull` command to download a copy of the CodeQL Action and bundles to a local folder. + +**Optional Arguments:** +* `--cache-dir` - The directory in which to store data downloaded from GitHub.com. If not specified a directory next to the sync tool will be used. + +Next copy the sync tool and cache directory to another machine which has access to GitHub Enterprise Server. + +Now use the `./codeql-action-sync push` command to upload the CodeQL Action and bundles to GitHub Enterprise Server. + +**Required Arguments:** +* `--destination-url` - The URL of the GitHub Enterprise Server instance to push the Action to. +* `--destination-token` - A [Personal Access Token](https://docs.github.com/en/enterprise/user/github/authenticating-to-github/creating-a-personal-access-token) for the destination GitHub Enterprise Server instance. The token should be granted at least the `public_repo` scope. If the destination repository is in an organization that does not yet exist, your token will need to have the `site_admin` scope in order to create the organization. The organization can also be created manually or an existing organization used. + +**Optional Arguments:** +* `--cache-dir` - The directory to which the Action was previously downloaded. +* `--destination-repository` - The name of the repository in which to create or update the CodeQL Action. If not specified `github/codeql-action` will be used. diff --git a/docs/logo.png b/docs/logo.png new file mode 100644 index 0000000000000000000000000000000000000000..95138a5af42c0c39eb3f4d80a05e6bb42cffa843 GIT binary patch literal 2833 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + Code QL + + + + + + + + + + + + + + Code QL + + + + + + + + + + + + + + + + + + + + + + + + + Created with Sketch. + +