diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index e64b0f9..184339c 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,8 +1,8 @@ * @kelly-sovacool /.github/ @kelly-sovacool -/docs/lucidcharts* @kopardev -/docs/conda-mamba/conda-to-mamba @kopardev /docs/HPCDME @kopardev /docs/UCSC @kopardev -/docs/github/guide @kopardev +/docs/conda-mamba/conda-to-mamba @kopardev /docs/generative-AI/copilot-cli.md @kopardev +/docs/github/guide @kopardev +/docs/lucidcharts* @kopardev diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..443fa0a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,48 @@ +name: Bug report +description: Report something that is broken or incorrect +labels: bug +body: + - type: markdown + attributes: + value: | + Before you post this issue, please check existing Issues and Discussions to see if your problem has already been reported or solved. If you are unsure, please ask in the [CHAMPAGNE forum](https://forum.ccbr.medschl.cam.ac.uk/c/champagne) for help. + + - type: textarea + id: description + attributes: + label: Description of the bug + description: A clear and concise description of what the bug is. + validations: + required: true + + - type: textarea + id: command_used + attributes: + label: Command used and terminal output + description: Steps to reproduce the behaviour. Please paste the command you used to launch the pipeline and the output from your terminal. + render: console + placeholder: | + $ nextflow run ... + + Some output where something broke + + - type: textarea + id: files + attributes: + label: Relevant files + description: | + Please drag and drop any relevant files here. Create a `.zip` archive if the extension is not allowed. + Your verbose log file `.nextflow.log` is often useful _(this is a hidden file in the directory where you launched the pipeline)_ as well as custom Nextflow configuration files. + If the bug is related to a GUI, add screenshots to help explain your problem. + + - type: textarea + id: system + attributes: + label: System information + description: | + * Nextflow version _(eg. 21.10.3)_ + * Hardware _(eg. HPC, Desktop)_ + * Executor _(eg. slurm, local, awsbatch)_ + * Container engine: _(e.g. Docker, Singularity)_ + * OS _(eg. Ubuntu Linux, macOS)_ + * Version of CCBR/CHAMPAGNE _(eg. 1.0, 1.8.2)_ diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..c1f3832 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,4 @@ +contact_links: + - name: Discussions + url: https://github.com/CCBR/HowTos/discussions + about: Please ask and answer questions here. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..a53fa76 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,11 @@ +name: Feature request +description: Suggest an idea for the pipeline +labels: enhancement +body: + - type: textarea + id: description + attributes: + label: Description of feature + description: Please describe your suggestion for a new feature. It might help to describe a problem or use case, plus any alternatives that you have considered. Before submitting, please check if there is already an open issue for the same feature. + validations: + required: true diff --git a/CHANGELOG.md b/CHANGELOG.md index 269ea24..3533d79 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,7 +1,8 @@ ## HowTos development version -- Publishing Shiny apps to NCI's Posit Connect servers (#53, @escauley) +- New guide: Publishing Shiny apps to NCI's Posit Connect servers (#53, @escauley) - Update the Zenodo guide with current CCBR practices (#55, @kelly-sovacool) +- Create an overview of authentication with GitHub, a guide on using SSH keys with GitHub, and how to use fine-grained tokens. (#61, @kelly-sovacool) ## HowTos 1.0.0 diff --git a/docs/GitHub/authentication/index.qmd b/docs/GitHub/authentication/index.qmd new file mode 100644 index 0000000..672dbab --- /dev/null +++ b/docs/GitHub/authentication/index.qmd @@ -0,0 +1,9 @@ +--- +title: Authentication with GitHub +date: 2026-02-09 +--- + +- [SSH Keys](./ssh-keys/) - **recommend** for running git commands from the terminal +- [GitHub Apps](https://ccbr.github.io/actions/gh-app-auth.html) - for GitHub Actions and other automation platforms +- [Fine-grained tokens](./tokens/fine-grained.qmd) - needed for **Code Ocean** and other platforms requiring a token +- [Classic tokens](./tokens/classic.qmd) - no longer in use as of March 1st, 2026 diff --git a/docs/GitHub/authentication/ssh-keys/add-ssh-key-browser.png b/docs/GitHub/authentication/ssh-keys/add-ssh-key-browser.png new file mode 100644 index 0000000..72bf2cb Binary files /dev/null and b/docs/GitHub/authentication/ssh-keys/add-ssh-key-browser.png differ diff --git a/docs/GitHub/authentication/ssh-keys/clone-ssh.png b/docs/GitHub/authentication/ssh-keys/clone-ssh.png new file mode 100644 index 0000000..c88ecd0 Binary files /dev/null and b/docs/GitHub/authentication/ssh-keys/clone-ssh.png differ diff --git a/docs/GitHub/authentication/ssh-keys/index.qmd b/docs/GitHub/authentication/ssh-keys/index.qmd new file mode 100644 index 0000000..e5bedbe --- /dev/null +++ b/docs/GitHub/authentication/ssh-keys/index.qmd @@ -0,0 +1,387 @@ +--- +title: "Connect to GitHub with SSH keys" +author: "[Kelly Sovacool](https://github.com/kelly-sovacool)" +date: 2026-02-09 +execute: + eval: false +--- + +## Background + +If you have been using a personal access token (PAT) to authenticate with +GitHub, it will become much harder to do so after March 1st, 2026. + +Classic PATs are authorized for all resources that a GitHub account has access +to, so you could create a single classic PAT and use it in lieu of a password +for any repository in any organization that you have access to. However, this +poses a security risk, so classic PATs will be phased out on March 1st, 2026. + +GitHub is recommending switching to fine-grained PATs. However, fine-grained +PATs can only be authorized to access resources for a single organization at a +time. This means you would need to create a separate fine-grained PAT for every +GitHub organization you have access to (e.g. CCBR, NIDAP-Community, NCI-RBL, +etc.), and then update your git credential manager to make sure it uses the +correct PAT for the correct organization. Additionally, NCI Enterprise requires +that PATs must expire every 90 days, so you would need to update them regularly. + +Instead, we recommend using Secure Shell Protocol (SSH) for authentication with +GitHub. Follow the guide below for step-by-step instructions on creating SSH +keys and configuring SSH to work with your GitHub account. + +:::{.callout-tip} +You will need to repeat the steps in this guide for every machine that you use +with GitHub, as each one will need its own SSH key file. +Most CCBR members will need to generate an SSH key for each of the following: + +1. GFE laptop +1. biowulf/helix +1. FRCE +1. Any other HPCs or servers you use with git/GitHub +::: + +## Create a new SSH key for use with GitHub + +### Generate a new SSH key + +Run the following command to generate a new key, replacing +`your_email@example.com` with the primary email associated with your GitHub +account. For CCBR members, it should be your NIH email e.g. +`firstname.lastname@nih.gov`. + +```{.bash filename="sh"} +ssh-keygen -t ed25519 -C "your_email@example.com" +``` + +It will then prompt you with a location to save the key. **Press enter** to +accept the default location. + +```{.email filename="output"} +Generating public/private ed25519 key pair. +Enter file in which to save the key (/Users/$USER/.ssh/id_ed25519): +``` + +You can **press enter again** for no password (recommended). If you choose to +enter a password, you'll [need to set up your +keychain](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/working-with-ssh-key-passphrases) +to store it. + +```{.email filename="output"} +Enter passphrase for "/Users/$USER/.ssh/id_ed25519" (empty for no passphrase): +``` + +### Add the new SSH key to the ssh-agent + +Start up the ssh-agent to run in the background: + +```{.bash filename="sh"} +eval "$(ssh-agent -s)" +``` + +It will report the process ID of the ssh-agent: +```{.email filename="output"} +Agent pid 46212 +``` + +Next, if you're running this on macOS, you'll need to modify the ssh config file +to automatically load keys. If you're on Linux, there's no need to modify your +`~/.ssh/config`. For macOS, open `~/.ssh/config` in your preferred text editor +and add these lines: + +```{.email filename="~/.ssh/config"} +Host github.com + AddKeysToAgent yes + IgnoreUnknown UseKeychain + IdentityFile ~/.ssh/id_ed25519 +``` + +Now add the ssh key to the agent: + +```{.bash filename="sh"} +ssh-add ~/.ssh/id_ed25519 +``` + +It will report that the new identity was added: + +```{.email filename="output"} +Identity added: /Users/$USER/.ssh/id_ed25519 (firstname.lastname@nih.gov) +``` + +### Add the new SSH key to your GitHub Account + +Select one of the methods below for adding the new SSH key to your GitHub Account. + +
+ +**Via the web browser** + + +First, print the contents of the public key file and copy it to your clipboard: + +```{.bash filename="sh"} +cat ~/.ssh/id_ed25519.pub +``` + +In a web browser, go to + +Click `New SSH key` + +![](./new-ssh-key.png) + +1. Add a title with a brief description of the key. For example, I use "NCI macOS +laptop" for the key I use on my GFE laptop and "biowulf" for the biowulf HPC. +1. Select `authentication` for the type of key. +1. Paste the key into the `Key` field. +1. Click `Add SSH key` + +![](./add-ssh-key-browser.png) + +
+ +
+ +**Via the GitHub CLI** + + +This option works well on a laptop, but not so well on servers such as biowulf. + +If you do not already have the GitHub CLI, install it now: + + +#### Log in via the gh CLI + +Authenticate to GitHub via the `gh` CLI with the proper scope for adding ssh keys: + +```{.bash filename="sh"} +gh auth login -h github.com -s admin:public_key +``` + +Follow the prompts to log in to GitHub via the web browser, or however you prefer. + +```{.email filename="output"} +? Where do you use GitHub? GitHub.com +? What is your preferred protocol for Git operations on this host? HTTPS +? Authenticate Git with your GitHub credentials? Yes +? How would you like to authenticate GitHub CLI? Login with a web browser + +! First copy your one-time code: XXXX-XXXX +Press Enter to open https://github.com/login/device in your browser... +✓ Authentication complete. +- gh config set -h github.com git_protocol https +✓ Configured git protocol +✓ Logged in as github-username +``` + +#### Add the SSH key to your account + +Run the following command to add the key, replacing the title with a brief +description of the key. For example, I use "NCI macOS laptop" for the key I use +on my GFE laptop and "biowulf" for the biowulf HPC. + +```{.bash filename="sh"} +gh ssh-key add ~/.ssh/id_ed25519.pub --type authentication --title "NCI macOS laptop" +``` + +```{.email filename="output"} +✓ Public key added to your account +``` +
+ +### Test your connection + +Try to connect to GitHub via ssh: +```{.bash filename="sh"} +ssh -T git@github.com +``` + +You'll see a warning. Type "yes" and press Enter: + +```{.email filename="output"} +The authenticity of host 'github.com (IP ADDRESS)' can't be established. +ED25519 key fingerprint is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU. +Are you sure you want to continue connecting (yes/no)? +``` + +If successful, you'll see this message: +```{.email filename="output"} +Hi GITHUB-USERNAME! You've successfully authenticated, but GitHub does not provide shell access. +``` + +## Authorize the SSH key for GitHub organizations + +For each NCI Enterprise GitHub organization that you are a member of, you will +need to configure the key for single sign-on. + +In a web browser, go to + +Next to the new SSH key you just added, click `Configure SSO`: + +![](./ssh-config-sso.png) + +Click `Authorize` for the organization you want to add: + +![](./sso-authorize.png) + +Click `continue` and follow the prompts. + +![](./nci-sso.png){width=400px} + +Repeat the above steps for each organization you want to configure (e.g. `CCBR`, +`NIDAP-Community`, etc.) + +## Configure your cloned repositories to use SSH + +If this is the first time you're setting up SSH keys with GitHub, +you probably cloned your repositories using HTTPS. +Go to one of your repos and list the remotes you have configured: + +```{.bash filename="sh"} +git remote -v +``` + +If the url begins with `https`, it was cloned via HTTPS: + +```{.email filename="output"} +origin https://github.com/ORGANIZATION/REPOSITORY (fetch) +origin https://github.com/ORGANIZATION/REPOSITORY (push) +``` + +You'll need to change the remote URL to use SSH instead: + +```{.bash filename="sh"} +git remote set-url origin git@github.com:ORGANIZATION/REPOSITORY.git +``` + +Replace `ORGANIZATION` and `REPOSITORY` with their actual values, e.g. this repo +would be `CCBR/HowTos`. + +You will need to repeat this for every repo you have cloned on your machine. +But you don't have to do it manually: let's automate it! + +### Automate: change the remote for all repositories + +We can automate this with a bash command to find all git repositories, determine +the organization and repository name, and set the remote url to use SSH instead +of HTTPS. In my case, I clone all of my repositories to a directory in +`~/projects`. The following command finds all of the git repos I have cloned: + +```{.bash filename="sh"} +find ~/projects -name ".git" -type d +``` + +You should replace `~/projects` with the path where you clone your repos, then +run the above command to make sure it can find the cloned repos. + +For an individual repo, you can find out the remote url with the following +(replace `~/projects/path/to/repo/.git` with the actual path for your example +repo): + +```{.bash filename="sh"} +git -C ~/projects/path/to/repo/.git config --get remote.origin.url +``` +```{.email filename="output"} +https://github.com/ORGANIZATION/REPOSITORY.git +``` + +We can use `sed` to extract the name of the organization or username and repo on +GitHub: + +```{.bash filename="sh"} +git -C ~/projects/path/to/repo/.git config --get remote.origin.url | sed -E 's|.*[:/]([^/]+)/(.*)\.git/?$|\1/\2|; s|.*[:/]([^/]+)/([^/]+)/?$|\1/\2|') +``` +```{.email filename="output"} +ORGANIZATION/REPOSITORY +``` + +Finally, we can use the `git remote` command to modify the remote url to use SSH +rather than HTTPS. Putting it all together, here's the full command: + +#### Command to set all remotes to use SSH + +```{.bash filename="sh" code-line-numbers="true"} +find ~/projects -name ".git" -type d 2>/dev/null | sed 's|/.git$||' | while read repo; do + org_repo=$(git -C "$repo" config --get remote.origin.url 2>/dev/null | sed -E 's|.*[:/]([^/]+)/(.*)\.git/?$|\1/\2|; s|.*[:/]([^/]+)/([^/]+)/?$|\1/\2|') + echo $org_repo + git -C $repo remote set-url origin git@github.com:${org_repo}.git +done +``` + +The above command will print the organization & repository name as it goes so +you can monitor the progress. + +:::{.callout-tip} +Make sure you replace `~/projects` with the path on your machine where you clone +your repositories. +::: +:::{.callout-warning} +Be careful running this command on shared machines such as the Biowulf HPC. +You do not want to accidentally edit repos belonging to other users! +You may need to first create a text file containing paths to all of your repos, +and iterate over that instead of the `find` command for the `while` loop. +::: + +### Cloning new repos + +When you make a new clone of a repository, you will need to use the SSH url from +now on. You can find the SSH url on a repo's GitHub repository page by clicking +`Code`, then clicking the `SSH` tab. + +![](./clone-ssh.png) + +Copy the URL to your clipboard, then in a terminal run `git clone` using this +url: + +```{.bash filename="sh"} +git clone git@github.com:ORGANIZATION/REPOSITORY.git +``` + +```{.email filename="output"} +Cloning into 'REPOSITORY'... +remote: Enumerating objects: 3650, done. +remote: Counting objects: 100% (405/405), done. +remote: Compressing objects: 100% (206/206), done. +remote: Total 3650 (delta 281), reused 240 (delta 194), pack-reused 3245 (from 2) +Receiving objects: 100% (3650/3650), 171.17 MiB | 30.70 MiB/s, done. +Resolving deltas: 100% (2135/2135), done. +``` + +You can test that your SSH key works with your repo by creating a new branch and +pushing it: + +```{.bash filename="sh"} +git switch -c test-ssh +git push +``` + +You'll see a message like the following if it's successful: + +```{.email filename="output"} +Enumerating objects: 14, done. +Counting objects: 100% (14/14), done. +Delta compression using up to 10 threads +Compressing objects: 100% (10/10), done. +Writing objects: 100% (11/11), 522.94 KiB | 16.87 MiB/s, done. +Total 11 (delta 2), reused 0 (delta 0), pack-reused 0 (from 0) +remote: Resolving deltas: 100% (2/2), completed with 2 local objects. +remote: +remote: Create a pull request for 'test-ssh' on GitHub by visiting: +remote: https://github.com/ORGANIZATION/REPOSITORY/pull/new/test-ssh +remote: +To github.com:ORGANIZATION/REPOSITORY.git + * [new branch] test-ssh -> test-ssh +branch 'test-ssh' set up to track 'origin/test-ssh'. +``` + +### Help and Troubleshooting + +Check out the GitHub Docs for more information about authenticating with SSH +keys. + +- How to create an ssh key: +- How to add an ssh key to your account: +- Test your connection: + +If you run into problems, first make sure you correctly followed all of the +steps above, then try searching for your problem in the GitHub docs. If you're +still not able to solve it, [open a question in +Discussions](https://github.com/CCBR/HowTos/discussions/new?category=q-a) to ask +for help. diff --git a/docs/GitHub/authentication/ssh-keys/nci-sso.png b/docs/GitHub/authentication/ssh-keys/nci-sso.png new file mode 100644 index 0000000..034cbef Binary files /dev/null and b/docs/GitHub/authentication/ssh-keys/nci-sso.png differ diff --git a/docs/GitHub/authentication/ssh-keys/new-ssh-key.png b/docs/GitHub/authentication/ssh-keys/new-ssh-key.png new file mode 100644 index 0000000..42cc8be Binary files /dev/null and b/docs/GitHub/authentication/ssh-keys/new-ssh-key.png differ diff --git a/docs/GitHub/authentication/ssh-keys/ssh-config-sso.png b/docs/GitHub/authentication/ssh-keys/ssh-config-sso.png new file mode 100644 index 0000000..097048a Binary files /dev/null and b/docs/GitHub/authentication/ssh-keys/ssh-config-sso.png differ diff --git a/docs/GitHub/authentication/ssh-keys/sso-authorize.png b/docs/GitHub/authentication/ssh-keys/sso-authorize.png new file mode 100644 index 0000000..2ad9fda Binary files /dev/null and b/docs/GitHub/authentication/ssh-keys/sso-authorize.png differ diff --git a/docs/GitHub/authentication/tokens/classic.qmd b/docs/GitHub/authentication/tokens/classic.qmd new file mode 100644 index 0000000..9ea7ac9 --- /dev/null +++ b/docs/GitHub/authentication/tokens/classic.qmd @@ -0,0 +1,14 @@ +--- +title: "Classic Personal Access Tokens" +author: "[Kelly Sovacool](https://github.com/kelly-sovacool)" +date: 2026-02-09 +--- + +:::{.callout-important} +Classic Personal Access Tokens (PATs) will be completely phased out by March +1st, 2026. Please switch to using [SSH +keys](/docs/GitHub/authentication/ssh-keys), [fine-grained +tokens](/docs/GitHub/authentication/tokens/fine-grained.qmd), or [github +apps](https://ccbr.github.io/actions/gh-app-auth.html) as appropriate for your +use-case. +::: diff --git a/docs/GitHub/authentication/tokens/fine-grained.qmd b/docs/GitHub/authentication/tokens/fine-grained.qmd new file mode 100644 index 0000000..8f21172 --- /dev/null +++ b/docs/GitHub/authentication/tokens/fine-grained.qmd @@ -0,0 +1,82 @@ +--- +title: "Fine-Grained Personal Access Tokens" +author: "[Kelly Sovacool](https://github.com/kelly-sovacool)" +date: 2026-02-09 +--- + +:::{.callout-tip} +If you are trying to authenticate to GitHub for syncing repos from your laptop +(i.e. `git push` / `git pull`), we recommending using SSH keys instead of +fine-grained tokens. See the [instructions for using SSH keys with +GitHub](/docs/GitHub/authentication/ssh-keys) for details. +::: + +Fine-grained tokens can be used to authenticate with GitHub when using the +GitHub API or syncing repositories over HTTPS. Each token can be granted +specific, granular permissions for the types of actions they can make (e.g. +editing repo contents, triggering github actions, etc.), and they can be scoped +to work for an entire account/organization or only specific repositories within +an organization. One significant limitation is each fine-grained token can only +be granted permissions for one account or organization at a time; this is +intentionally for security reasons. Additionally, NCI Enterprise requires GitHub +tokens to expire at least every 90 days, so you will need to regenerate them +regularly. + +In most cases you should instead use either [SSH +keys](/docs/GitHub/authentication/ssh-keys) or [GitHub +apps](https://ccbr.github.io/actions/gh-app-auth.html), but some times you do +need to use a fine-grained token such as for [Code +Ocean](https://docs.codeocean.com/user-guide/git-provider-integration-guide/setting-up-the-integration) + +## Creating a new token + +Navigate to the fine-grained tokens page on GitHub: + + +Click `Generate new token` + +![](./generate.png) + +Fill out the token name and description. It should be descriptive enough that +you will know why you created the token and how it is being used when you come +back to this page in three months. + +Select the **Resource owner**, set the Expiration to **90 days**, and select +**All repositories** for access. The token will have access to any repository in +the resource owner (an organization or your personal account) that you have +access to. + +![](./token-title.png) + +Under **Permissions**, click `Add permissions` and add the scopes that the token +will need to access. Most likely you will need to add `Read and write` access +for `Contents`, and perhaps also `Workflows`. + +![](./permissions.png) + +Once you're ready, click `Generate token`. + +Copy the token to your clipboard. + +:::{.callout-warning} +Protect the token just like you protect your passwords! Do not share it with +anyone. +::: + +### Code Ocean + +If you're using this token for Code Ocean, you'll need to add it to your Code +Ocean Account. In Code Ocean, click the Account icon, go to `Credentials`, click +`Add Credentials`, and select `GitHub Credentials`. + +![](https://docs.codeocean.com/user-guide/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FZcjcjJxTZ10AvAt98Uzr%2Fblobs%2FeAVIvkLZQEX6mxEXm057%2FAccountPage.png&width=768&dpr=2&quality=100&sign=a591b5c7&sv=2) + +Enter your GitHub username and paste in the **token** you just created. + +![](https://docs.codeocean.com/user-guide/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FZcjcjJxTZ10AvAt98Uzr%2Fblobs%2FLZIPZhPQhDRErErvUXfb%2FGitHub_credentials.png&width=768&dpr=2&quality=100&sign=993f7233&sv=2) + +Click `Add Credential`. You're ready to sync repos with GitHub in Code Ocean! + +## Help + +For more information, see [the GitHub docs](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token). diff --git a/docs/GitHub/authentication/tokens/generate.png b/docs/GitHub/authentication/tokens/generate.png new file mode 100644 index 0000000..69ffaaf Binary files /dev/null and b/docs/GitHub/authentication/tokens/generate.png differ diff --git a/docs/GitHub/authentication/tokens/permissions.png b/docs/GitHub/authentication/tokens/permissions.png new file mode 100644 index 0000000..9b41801 Binary files /dev/null and b/docs/GitHub/authentication/tokens/permissions.png differ diff --git a/docs/GitHub/authentication/tokens/token-title.png b/docs/GitHub/authentication/tokens/token-title.png new file mode 100644 index 0000000..850a4bc Binary files /dev/null and b/docs/GitHub/authentication/tokens/token-title.png differ diff --git a/docs/GitHub/guide/0_overview.md b/docs/GitHub/guide/0_overview.md index d661146..ac41c79 100644 --- a/docs/GitHub/guide/0_overview.md +++ b/docs/GitHub/guide/0_overview.md @@ -1,15 +1,18 @@ --- title: Overview of GitHub Topics author: "[Samantha Sevilla](https://github.com/slsevilla) & [Vishal Koparde](https://github.com/kopardev)" +date: 2023-04-11 --- ## Getting set-up and familiar with GitHub + - [Preparing your environment](1_howto_setup.md): - Describes how to create a PAT, add GH to your bash profile and use password-less login features -- [Basic Commands](2_howto_functions.md): - - Describes basic functions to be used with this SOP +- [Basic Commands](2_howto_commands.md): + - Describes basic git commands to be used with this SOP ## Basics + - [Creating your GitHub repo](3_basic_repo.md): - Provides information on how to setup a GitHub repository under CCBR and the use of templates - [Creating your Documentation](4_basic_docs.md): diff --git a/docs/GitHub/guide/1_howto_setup.md b/docs/GitHub/guide/1_howto_setup.md index 0a220c7..3e3217e 100644 --- a/docs/GitHub/guide/1_howto_setup.md +++ b/docs/GitHub/guide/1_howto_setup.md @@ -1,24 +1,49 @@ +--- +date: 2023-04-27 +date-modified: 2026-02-09 +author: "[Kelly Sovacool](https://github.com/kelly-sovacool)" +--- + # GitHub Setup: Preparing the Environment -## Using GitHub CLI -The `gh` is installed on Biowulf at `/data/CCBR_Pipeliner/db/PipeDB/bin/gh_1.7.0_linux_amd64/bin/gh`. You can run the following lines to edit your `~/.bashrc` file to add `gh` to your `$PATH`: -```bash -echo "export PATH=$PATH:/data/CCBR_Pipeliner/db/PipeDB/bin/gh_1.7.0_linux_amd64/bin" >> ~/.bashrc -source ~/.bashrc -``` +git is installed by default on macOS and Linux. + +You can also optionally install the GitHub CLI for easy access to GitHub-related commands from your terminal. -Alternatively, you can use the `git` commands provided through a Biowulf module -```bash -module load git +## GitHub CLI + +On macOS you can install the GitHub CLI with homebrew: +```sh +brew install gh ``` -## Creating PAT for GH +For other platforms, see the [github cli installation instructions](https://github.com/cli/cli?tab=readme-ov-file#installation). + +### Log in -Personal Access Token (PAT) is required to access GitHub (GH) without having to authenticate by other means (like password) every single time. You will need [gh cli](https://cli.github.com/) installed on your laptop or use `/data/CCBR_Pipeliner/db/PipeDB/bin/gh_1.7.0_linux_amd64/bin/gh` on Biowulf, as described above. You can create a PAT by going [here](https://github.com/settings/tokens). Then you can copy the PAT and save it into a file on Biowulf (say `~/gh_token`). Next, you can run the following command to set everything up correctly on Biowulf (or your laptop) +Log in to GitHub via the CLI and follow the prompts: + +```sh +gh auth login ``` -gh auth login --with-token < ~/git_token + +## Configure git + +On any machine where you use git (e.g. your laptop, biowulf, frce, etc.), you +will need to configure your name and email address. + +```{.bash filename="sh"} +git config --global user.name "Firstname Lastname" +git config --global user.email YOUR_EMAIL@example.com ``` -## Password-less Login +Make sure you replace `YOUR_EMAIL@example.com` with the primary email associated +with your GitHub account. For CCBR members, this should be your NIH email i.e. +`firstname.lastname@nih.gov`. + +## Authenticating git with GitHub -If you hate to re-enter (username and) password every time you push/pull to/from github (or mkdocs gh-deploy), then it is totally worthwhile to spend a couple minutes to set up SSH keys for auto-authentication. The instructions to do this are available [here](https://blog.corsego.com/aws-cloud9-github-ssh). +It is possible to use a personal access token (PAT) to authenticate with GitHub, +but we now recommend using SSH Keys instead. [View the instructions on setting +up SSH keys](/docs/GitHub/authentication) and follow all of the steps before +proceeding. diff --git a/docs/GitHub/guide/2_howto_functions.md b/docs/GitHub/guide/2_howto_commands.md similarity index 76% rename from docs/GitHub/guide/2_howto_functions.md rename to docs/GitHub/guide/2_howto_commands.md index 344a30b..4906029 100644 --- a/docs/GitHub/guide/2_howto_functions.md +++ b/docs/GitHub/guide/2_howto_commands.md @@ -1,5 +1,11 @@ -# GitHub HowTo: Basic Functions -The following outlines basic GitHub function to `push` and `pull` from your repository. It also includes information on creating a new branch and deleting a branch. These commands should be used in line with guidance on [GitHub Repo Management](https://ccbr.github.io/HowTos/GitHub/sop_repo/). +--- +author: "[Samantha Sevilla](https://github.com/slsevilla) & [Vishal Koparde](https://github.com/kopardev)" +date: 2023-04-27 +--- + +# GitHub HowTo: Basic Commands + +The following outlines basic GitHub commands to `push` and `pull` from your repository. It also includes information on creating a new branch and deleting a branch. These commands should be used in line with guidance on [GitHub Repo Management](https://ccbr.github.io/HowTos/GitHub/sop_repo/). ### Pushing local changes to remote @@ -20,6 +26,10 @@ Push changes to branch named `new_feature` git push origin new_feature ``` +:::{.callout-tip} +If this command returned a "Permission Denied" error, make sure you have properly [set up authentication with SSH keys.](/docs/GitHub/authentication/ssh-keys) +::: + ### Pulling remote changes to local Pull changes from branch `new_feature` into your branch `old_feature` @@ -29,7 +39,7 @@ git pull new_feature ``` If you have non-compatible changes in the `old_feature` branch, there are two options: -1) ignore local changes and pull remote anyways. This will delete the changes you've made to your remote respository. +1) ignore local changes and pull remote anyways. This will delete the changes you've made to your remote repository. ```bash git reset --hard git pull diff --git a/docs/GitHub/guide/3_basic_repo.md b/docs/GitHub/guide/3_basic_repo.md index b5c3956..fc9adb9 100644 --- a/docs/GitHub/guide/3_basic_repo.md +++ b/docs/GitHub/guide/3_basic_repo.md @@ -1,3 +1,8 @@ +--- +author: "[Samantha Sevilla](https://github.com/slsevilla) & [Vishal Koparde](https://github.com/kopardev)" +date: 2023-04-27 +--- + # GitHub Basics: Repository ## Repository Location @@ -51,9 +56,13 @@ gh repo create CCBR/techdev_ \ Once the repo is created, then you can clone a local copy of the new repository: ```bash -gh repo clone CCBR/.git +git clone git@github.com:CCBR/.git ``` +:::{.callout-important} +Make sure you use SSH to clone repositories instead of HTTPS. See the [instructions for setting up SSH keys](/docs/GitHub/authentication/ssh-keys/index.html#cloning-new-repos) for details. +::: + ## Minimal helper components If you start from one of the above templates, you'll have these files already. diff --git a/docs/GitHub/guide/4_basic_docs.md b/docs/GitHub/guide/4_basic_docs.md index 031c445..053f91a 100644 --- a/docs/GitHub/guide/4_basic_docs.md +++ b/docs/GitHub/guide/4_basic_docs.md @@ -1,4 +1,10 @@ +--- +author: "[Samantha Sevilla](https://github.com/slsevilla) & [Vishal Koparde](https://github.com/kopardev)" +date: 2023-04-27 +--- + # GitHub Basics: Documentation + GitHub [Pages](https://pages.github.com/) is quick and easy way to build static websites for your GitHub repositories. Essentially, you write pages in [Markdown](https://www.markdownguide.org/) which are then rendered to HTML and hosted on GitHub, free of cost! CCBR has used GitHub pages to provide extensive, legible and organized documentation for our pipelines. Examples are included below: diff --git a/docs/GitHub/guide/5_basic_actions.md b/docs/GitHub/guide/5_basic_actions.md index e74bd9c..a2aa33d 100644 --- a/docs/GitHub/guide/5_basic_actions.md +++ b/docs/GitHub/guide/5_basic_actions.md @@ -1,3 +1,8 @@ +--- +author: "[Samantha Sevilla](https://github.com/slsevilla) & [Vishal Koparde](https://github.com/kopardev)" +date: 2023-04-27 +--- + # GitHub Basics: GitHub Actions The following describe the minimum GitHub actions that should be deployed with any production pipeline. The actions are automatically provided via the cookiecutter templates: [NextFlow](https://github.com/CCBR/CCBR_NextflowPipelineCookiecutter) and [Snakemake](https://github.com/CCBR/CCBR_SnakemakePipelineCookiecutter). @@ -24,3 +29,7 @@ The following describe the minimum GitHub actions that should be deployed with a When an issue or PR is assigned to a CCBR member, this action will automatically add it to their personal GitHub Project, if they have one. This file can be copy and pasted exactly as-is into any CCBR repo from [here](https://github.com/CCBR/CCBR_NextflowTemplate/blob/main/.github/workflows/projects.yml). + +## Advanced + +View the [GitHub Actions demo](/docs/GitHub/github-actions-demo.qmd) for an in-depth guide for creating your own GitHub Actions workflows. diff --git a/docs/GitHub/guide/6_howto_precommit.md b/docs/GitHub/guide/6_howto_precommit.md index 916e002..f37d347 100644 --- a/docs/GitHub/guide/6_howto_precommit.md +++ b/docs/GitHub/guide/6_howto_precommit.md @@ -1,3 +1,9 @@ +--- +author: "[Samantha Sevilla](https://github.com/slsevilla) & [Ned Cauley](https://github.com/escauley)" +date: 2023-11-01 +date-modified: 2025-12-12 +--- + # GitHub HowTo: Pre-Commit Pre-commit should be added to all GitHub repositories on Biowulf and any clones created elsewhere to ensure cohesive and informative commit messages. After the creating the repository the following commands should be run in order to initialize the pre-commit hook, and establish the following requirements for all commit messages: diff --git a/docs/GitHub/guide/7_sop_projpipes.md b/docs/GitHub/guide/7_sop_projpipes.md index 649c96f..2b6f40f 100644 --- a/docs/GitHub/guide/7_sop_projpipes.md +++ b/docs/GitHub/guide/7_sop_projpipes.md @@ -1,9 +1,14 @@ +--- +author: "[Samantha Sevilla](https://github.com/slsevilla) & [Vishal Koparde](https://github.com/kopardev)" +date: 2023-05-08 +--- + # GitHub Best Practices: Projects and Pipelines - Users should follow these links to learn more about setting up the repository, before reviewing the best practices below: - [Preparing your environment](howto_setup.md) - - [Basic Commands](howto_functions.md) + - [Basic Commands](howto_commands.md) - [Creating your GitHub repo](basic_repo.md) - [Creating your Documentation](setup_docs.md) - [GitHub Actions](basic_actions.md) diff --git a/docs/GitHub/guide/8_sop_techdev.md b/docs/GitHub/guide/8_sop_techdev.md index 5c415c0..b4f2937 100644 --- a/docs/GitHub/guide/8_sop_techdev.md +++ b/docs/GitHub/guide/8_sop_techdev.md @@ -1,6 +1,7 @@ --- title: "GitHub Best Practices: TechDev projects" author: "[Samantha Sevilla](https://github.com/slsevilla)" +date: 2023-04-26 --- ## GitHub Best Practices @@ -8,7 +9,7 @@ author: "[Samantha Sevilla](https://github.com/slsevilla)" - Users should follow these links to learn more about setting up the repository, before reviewing the best practices below: - [Preparing your environment](/GitHub/1_howto_setup/) - - [Basic Commands](/GitHub/2_howto_functions/) + - [Basic Commands](/GitHub/2_howto_commands/) - [Creating your GitHub repo](/GitHub/3_basic_repo/) - [Creating your Documentation](/GitHub/4_setup_docs/) - [GitHub Actions](/GitHub/5_basic_actions/)