Publish App Code to GitHub

Last Updated: January 2023

GitHub is among the most popular git repositories and is an excellent place to publish open source code. In this tutorial you will learn how to setup a new GitHub repository and push your code to it. Be sure to properly sanitize your code before pushing it to GitHub (see: Prepare App for Publishing and Deploy).

Topics covered in this tutorial include:

  • Creating GitHub repositories

  • Initializing a local Git repository

  • Staging, removing staged files, and committing

  • .gitignore

  • Adding a remote and Pushing Code to GitHub

../../../_images/publish_solution.png

0. Start From Previous Solution (Optional)

If you wish to use the previous solution as a starting point:

git clone https://github.com/tethysplatform/tethysapp-earth_engine.git
cd tethysapp-earth_engine
git checkout -b prepare-publish-solution prepare-publish-solution-4.2

1. Create GitHub Account or Sign In

If you don't have a GitHub account yet, sign up using this link: https://github.com/join.

Sign in to your GitHub account using this link: https://github.com/login. After logging in, you'll be brought to your dashboard.

2. Create GitHub Repository

Create a new repository on GitHub as follows:

  1. Click on the New button located next to the header "Repositories", near the top of the left navigation menu.

  2. Select your username as the Owner.

  3. Enter "tethysapp-earth_engine" as the Repository name.

    Note

    It is recommended that you use the "tethysapp-" prefix on all Tethys app repositories.

  4. Enter the short description for your setup.py as the Description

  5. Leave all other values at their default value and press the Create repository button.

    Note

    You may have noticed options to initialize your repository with a README, .gitignore, and LICENSE file. These are excellent features for setting up a repository if you don't already have code. However, DO NOT use these features for this tutorial.

3. Initialize Local Git Repository

Before the code can be pushed to GitHub, you will need to initialize a git repository on your local machine and commit your code to it.

  1. Change into the directory containing the setup.py:

bash
cd tethysapp-earth_engine
  1. If you started from one of the previous solutions, you will need to purge the git repository before continuing

bash
rm -rf .git
  1. Initialize a local git repository:

bash
git init
  1. Stage all files for committing:

bash
git add .
  1. Review the list of staged files:

bash
git status
  1. If any of the files in the "Changes to be committed" list contain sensitive information they need to be removed. Also remove any files containing data that are not needed by the app such as Zip archives or Shapfiles that may be in the workspace directories. This can be done as follows:

bash
git rm --cached <path to file>

Tip

You can used patterns in git commands to more efficiently add or remove files. For example:

bash
git rm --cached *.json

Warning

DO NOT commit your Google Earth Engine service account key file.

  1. Once you have removed all files with sensitive data, commit the staged files as follows:

bash
git commit -m "First commit."

4. Update gitignore File

The .gitignore file is used to specify files that should not be committed or tracked by your git repository. The scaffold for Tethys apps includes a .gitignore file with common files that should be ignored for Tethys apps. Any files that you removed in the previous step are good candidates for adding to the .gitignore.

  1. Check the status of git again:

bash
git status
  1. Notice that the files that were previously staged to be committed are gone because you committed them in the last step. Any files that you removed, such as Zip files, Shapefiles, the JSON files containing your keys, or the directories containing them should be listed in the "Untracked files" section.

  2. Open the .gitignore file and add the following lines to exclude Shapefiles, Zip files, and JSON files:

python
*.shp
*.dbf
*.shx
*.zip
*.json

Tip

You can use the keyboard shortcut CTRL-H in Files to toggle showing hidden files (files that begin with a ".") like the .gitignore.

  1. Check the status of git again:

bash
git status
  1. Notice that the files and directories containing the excluded files are no longer listed under "Untracked files". You should also notice that the .gitignore file is listed under the "Changes not staged for commit" section.

  2. Add any additional files to the .gitignore to clear the "Untracked files" list.

  3. Stage the .gitignore file and commit it:

python
git add .gitignore
git commit -m "Adds zip files, shapefiles, and json files to gitignore."

5. Push Code to GitHub Repository

With the code committed to your local git repository, you can push the code to GitHub.

  1. Navigate to: https://github.com/<USERNAME>/tethysapp-earth_engine, replacing <USERNAME> with your GitHub username.

  2. Locate the code block under the heading "... or push an existing repository from the command line" and copy it.

  3. Run the commands that you copied to add your GitHub repository as the remote named "origin" and then push the code. It should be similar to these commands:

bash
git remote add origin git@github.com:<USERNAME>/tethysapp-earth_engine.git
git push -u origin main
  1. You should see output similar to the following:

bash
Enumerating objects: 59, done.
Counting objects: 100% (59/59), done.
Delta compression using up to 12 threads
Compressing objects: 100% (54/54), done.
Writing objects: 100% (59/59), 2.86 MiB | 1.30 MiB/s, done.
Total 59 (delta 3), reused 0 (delta 0)
remote: Resolving deltas: 100% (3/3), done.
To github.com:<USERNAME>/tethysapp-earth_engine.git
 * [new branch]      main -> main
Branch 'main' set up to track remote branch 'main' from 'origin'.
  1. Navigate to: https://github.com/<USERNAME>/tethysapp-earth_engine, refreshing the page if necessary to see your code on GitHub.

Note

Notice that the README.md is automatically rendered below the list of files. If you view the LICENSE file, a layman's summary is provided for the license that you provided.