Iter 0: Credentials Management, CI, and Issue Tracking
Iteration 0—Getting Started: Team Setup
This part of the setup mostly involves actions that occur on either the team’s shared repo or the team’s deployment platform:
- Set up credentials management for API keys used by the app
- Verify CI is working and is able to access all needed secrets/credentials
- Setup Issue Tracking on the team repo to keep track of who on the team is doing what
Pre-Plan Your Team Work
Before you rush through the setup, there are some steps which can (or must) be done individually, and others which are best done by assigning one or two people on a team to take them on. Always cooridinate with your team so you know the status of your project.
Credentials (and Secrets) Management
Credentials are things your app needs to run but need to be kept private, even if your app code is open source. A common example is an API key used to access an external service, or a passphrase necessary to establish a database connection. Collectively, these kinds of information are sometimes called “secrets”. Secrets are tricky to manage for several reasons:
-
You often want to safely store them/version them, but it has to be done in a way that keeps them safe from prying eyes, perhaps by encrypting them at rest
-
The secrets need to be shared with all developers and (usually) the CI system and the production system, again while keeping them secret
Rails provides us two ways of managing our secrets.
Encrypted Credientials (Option 1)
Some frameworks and web services (e.g. GitHub) provide support for managing certain types of secrets. Rails (since 5.2) provides a built-in mechanism, config/credentials.yml.enc. This file contains all the secrets needed by the app, but it is stored as an encrypted file; the decryption key is then managed as a single “master key” by adding it to GitHub (for CI) and to your deployment platform (for production).
These steps should be done on one copy of the repo, then the results pushed and everyone else pull.
Start by deleting the current config/credentials.yml.enc, if one exists, since we’re about to replace it by generating a new “master key” and a new credentials file:
EDITOR=vim bundle exec rails credentials:edit
# If working locally and you have VSCode:
EDITOR='code --wait' bundle exec rails credentials:edit
(If you don’t like vim, substitute your favorite editor, such as nano. Using nano on Codio (or in a browser-based IDE) can be tricky, because the Ctrl+O shortcut to save the file may be captured by the IDE; try Ctrl+X to close the editor and answer Y when prompted.) Save the file and exit vim.
This creates a new encryption key stored in the file master.key and a new credentials file.
Important idea: The master key file will not be versioned, but every “entity” that wants to run the app–each developer, the CI tests, the deployed app–needs access to its contents. Thus, each developer should locally store (but not version) a copy of this file, and we will store the file’s contents as an environment variable in both GitHub and the deployment platform.
Later, we will add more credentials to credentials.yml for Google OAuth, GitHub OAuth and the Geocodio API. For now, look at the value of secret_key_base in the file. You should be able to open a Rails console ( bundle exec rails c) and verify that the app can “see” this value:
Rails.application.credentials[:secret_key_base]
Rails.application.credentials.dig reads credentials from config/credentials.yml.enc by decrypting it with config/master.key. You could specify environment specific groups as follows in config/credentials.yml.enc:
production:
GOOGLE_CLIENT_ID: xxxx
GOOGLE_CLIENT_SECRET: xxx
development:
GOOGLE_CLIENT_ID: xxx
GOOGLE_CLIENT_SECRET: xxx
Then use the following syntax to read keys for specific environment:
Rails.application.credentials.dig(:production, :GOOGLE_CLIENT_ID)
Rails.application.credentials.dig(:development, :GOOGLE_CLIENT_ID)
(This step did not require you to change any files. It’s simply an introduction of how to use credentials in Rails.)
Managing .env files
An alternative to Rails’ encrypted credentials is using .env files. When using foreman (which you’re already using with bin/dev), environment variables are automatically loaded from .env files.
Create a .env file in your project root:
touch .env
Verify that .env is already in your .gitignore file.
grep '.env' .gitignore
Sample .env file:
# OAuth Credentials
GOOGLE_CLIENT_ID=your-google-client-id-here
GOOGLE_CLIENT_SECRET=your-google-client-secret-here
GITHUB_CLIENT_ID=your-github-client-id-here
GITHUB_CLIENT_SECRET=your-github-client-secret-here
# API Keys
GEOCODIO_API_KEY=your-api-key-here
# Rails Secret Key Base (optional, Rails generates one)
SECRET_KEY_BASE=your-very-long-secret-key-here
Access these in your Rails app:
ENV['GOOGLE_CLIENT_ID']
ENV['GOOGLE_CLIENT_SECRET']
These expressions return nil if the variable is missing. Use ENV.fetch('GOOGLE_CLIENT_ID') if a missing value should raise an error, or ENV.fetch('GOOGLE_CLIENT_ID', 'default_value') when a fallback is appropriate.
.env files are very simple to use and edit. However, because they are not committed they require coorindation amongst your team and you deployment environment.
Your team should pick only one approach to managing secrets in your application.
Render
Use this section if your course deploys to Render. The Heroku instructions below are retained for courses using Heroku; complete only the deployment section for your platform. In later instructions, references to the deployed app mean your Render app, and deploying means merging or pushing to the connected GitHub branch. Heroku CLI commands apply only to Heroku.
We are currently working on finding an alternate solution which would allow all 3 or 4 teammates to deploy the same application.
In the meantime, you should each create your own render deploy or can make a shared user account if you wish.
One teammate should prepare the repository changes below and merge them into main. For individual deployments, each teammate then creates a Blueprint in their own Render workspace, connected to the same team repository. Each deployment has its own URL, database, and environment variables. With a shared account, create the Blueprint once.
No CLI installation or deploy command is required for this workflow. Render builds from GitHub, and the configuration below deploys automatically when main changes.
1. Create the Blueprint file
Sign up at render.com and choose the workspace for your deployment. In the root of your ActionMap team repository, alongside Gemfile, create render.yaml. The starter does not include this file. A Blueprint is Render’s configuration for creating and connecting the services described in this file.
Paste the entire template below, replacing xx with your team number in all three names, including the fromDatabase reference:
databases:
- name: actionmap-db-xx
databaseName: actionmap
user: actionmap
plan: free
region: oregon
services:
- type: web
name: actionmap-xx
runtime: ruby
plan: free
region: oregon
branch: main
autoDeployTrigger: commit
buildCommand: "./bin/render-build.sh"
startCommand: "bundle exec puma -C config/puma.rb"
envVars:
- key: DATABASE_URL
fromDatabase:
name: actionmap-db-xx
property: connectionString
- key: RAILS_MASTER_KEY
sync: false
- key: RAILS_ENV
value: production
- key: RAILS_SERVE_STATIC_FILES
value: "true"
- key: RAILS_LOG_TO_STDOUT
value: "true"
- key: WEB_CONCURRENCY
value: "0"
- key: BUNDLE_WITHOUT
value: "development:test"
- key: NODE_VERSION
value: "22"
Keep the database and web service in the same workspace and region so the internal database connection works. DATABASE_URL is supplied automatically; do not paste database passwords into this file. WEB_CONCURRENCY keeps Puma in single-process mode for the free web service. Node 22 matches the development setup. Keep the starter’s Ruby version and dependency lockfiles committed. See the Blueprint reference and Node version configuration.
This template uses the encrypted credentials approach described above. If your team chose environment variables instead, replace the RAILS_MASTER_KEY entry with:
- key: SECRET_KEY_BASE
generateValue: true
Render generates that secret for the deployment. Add your API keys separately in the web service’s Environment page when you configure the integrations below. Render does not receive your ignored local .env file, and the Puma start command does not load it.
2. Create the build script
Create bin/render-build.sh in the same repository; this file is also absent from the starter. Paste:
#!/usr/bin/env bash
set -o errexit
bundle install
export NPM_CONFIG_INCLUDE=dev
npm ci
bundle exec rails assets:precompile
bundle exec rails db:prepare
The starter uses npm and package-lock.json. Its JavaScript build tools, including webpack, are in devDependencies, so NPM_CONFIG_INCLUDE=dev keeps them available during asset compilation. BUNDLE_WITHOUT excludes Ruby development and test gems while retaining the production PostgreSQL adapter.
db:prepare creates the tables and loads seeds for a new database, then applies pending migrations on later deployments. Do not add an unconditional db:seed or database reset to every build. A failed deployment may have already applied database changes; inspect the build logs and fix the error before retrying. Deleting the database loses its data and should not be the default response to a failed build.
Make the script executable, then commit the two new files on your working branch:
chmod +x bin/render-build.sh
git add render.yaml bin/render-build.sh
git commit -m "Add Render deployment configuration"
git push -u origin HEAD
Follow the pull request process from the previous page to merge into main. Before proceeding, confirm that GitHub’s main branch contains both files, as well as Gemfile.lock, package-lock.json, and, if using encrypted credentials, the team’s config/credentials.yml.enc.
3. Connect GitHub and deploy
In the Render dashboard, choose New > Blueprint, connect your team repository, and select main. If the repository is missing, check that Render’s GitHub integration has access to it; an organization owner may need to approve access. Render reads render.yaml and proposes a web service and Postgres database. Confirm both use the Free plan and the same region.
If using encrypted credentials, Render prompts for RAILS_MASTER_KEY. Paste the contents of the team’s local config/master.key, matching the committed config/credentials.yml.enc, then approve the Blueprint. Do not generate a different master key for each deployment of the same encrypted credentials file.
The master key is ignored by Git and must never be committed or put in render.yaml. Rails uses the environment variable to decrypt the versioned credentials file. People with sufficient access to the deployment settings can access its secrets, so treat those settings as private. Later, configure GitHub CI with the same key.
Wait for the deployment to finish and inspect the build and runtime logs. The free web service has no interactive shell, so database preparation runs in the build script. See Render’s Rails deployment guide.
4. Verify the deployed app and its integrations
Open the actual URL shown on the web service’s dashboard, typically https://actionmap-xx.onrender.com. Render may add a suffix to make the hostname unique, particularly when teammates deploy separately. Use that exact URL in your README, submissions, and OAuth settings.
Confirm that the home page loads with its styling and map, and that selecting a state loads its counties. A free web service sleeps after 15 minutes without traffic and can take about a minute to wake up. Allow for this when checking the app or recording your demo.
Skip the Heroku section and continue with Add GitHub, Google, and Geocodio API keys below, using your deployed URL for both OAuth callbacks:
https://YOUR-RENDER-HOSTNAME/auth/google_oauth2/callback
https://YOUR-RENDER-HOSTNAME/auth/github/callback
For individual deployments, register each deployment’s callback URL with the OAuth provider, or use separate OAuth clients with credentials configured for each deployment. Keep any development callback URLs you still need.
If using encrypted credentials, commit the updated encrypted file and merge it into main to redeploy. If using environment variables, set GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, and GEOCODIO_API_KEY on each Render web service’s Environment page and save with a redeploy. When storing the Geocodio key in encrypted credentials, the starter reads the lowercase key geocodio_api_key.
Finally, test Google and GitHub login and a representative search on the deployed app. Test login with an account other than the OAuth application’s owner, including any consent-screen or test-user setup required by the provider. Repeat the deployment checks after merging later work into main; later integrations also need their credentials on every deployment.
Heroku
Now we need to setup the app on Heroku and ensure that our credentials are available there. Again, this should be done by one person on behalf of the team.
If you’re not using our prebuilt Codio stack, you’ll need to install the Heroku CLI.
- The steps below should work even though you’re reusing your team’s Heroku app from earlier assignments. If you’re having trouble, try force-pushing to the Heroku remote, deleting and re-adding your Postgres add-on manually, or, if all else fails, asking course staff to reset your Heroku application entirely.
- Log in to Heroku CLI using
heroku login -iusing your API key as your password. - Run the following commands to connect your local repo to your heroku app, replacing
<xx>with your team number:
heroku teams
heroku apps -t esaas # list the apps you have access to.
heroku apps:favorites:add -a fa25-team-<xx>
heroku git:remote -a fa25-team-<xx>
(If you’ve properly set the stack from an earlier assignment, you may not need to redo the last step.)
- Heroku’s stacks are called buildpacks, and since our app uses Node, we need to tell Heroku to use buildpacks containing both Node and Ruby:
heroku buildpacks:add heroku/nodejs
heroku buildpacks:add heroku/ruby
Confirm that you have both installed, and make sure they are listed in the order mentioned above:
heroku buildpacks
If the buildpacks are not in the right order (which may happen because a previous CHIP already added heroku/ruby), you can use heroku buildpacks:remove to remove a pack before adding it again.
- Before you push to Heroku, make sure your changes get put on the main branch of your team’s repo. Follow the
PR once you've finished your part (For future reference)section on the previous page. Once your changes are merged into the main branch of your GitHub repo. Run the following commands to pull the changes into your local/Codio main branch.
git checkout main
git pull origin main
- You’re now ready to push your . Note that
.gitignoreincludes the master key fileconfig/master.key, since that secret should not be checked in to version control. Instead we will make the secret available to Heroku in a separate manual step.
git push heroku main # you may need --force as well if this is the first push from your 10.5 repository
- Next, setup the initial database on Heroku:
heroku run rails db:prepare
NOTE: If you have previously deployed a Rails app to this Heroku container, you will want to remove and recreate the debase.
# First, remove the current database
heroku addons:destroy heroku-postgresql
# Then add a new one
heroku addons:create heroku-postgresql
You should now be able to access your app using the (appname).herokuapp.com that you set up in the previous step.
- Run the following command to make
config/credentials.yml.encavailable on Heroku:
heroku config:set RAILS_MASTER_KEY="$(< config/master.key)"
This incantation echoes the contents of config/master.key in your local terminal and sets the Heroku environment variable RAILS_MASTER_KEY to that value. (You could also do this by displaying the file contents in the terminal and using copy-paste to set the value of the variable in Heroku’s “Application settings” for your app.) Rails can now use the value of that environment variable to decrypt the secrets file, but the value cannot be “seen” outside the Rails app and is not stored in any file that ever makes its way to Heroku or GitHub. Note the pattern here: The file containing the API keys and other secrets is versioned, in encrypted form; the encryption/decryption key is never saved anywhere as a file, but only made available as an environment variable. Later we will do the equivalent process to make the environment variable visible in GitHub for CI.
Add GitHub, Google, and Geocodio API keys
Now you need to update the credentials.yml.enc using EDITOR=vim bundle exec rails credentials:edit because the app includes “login with your Google account” and “login with GitHub”, both of which require API keys, and also uses the Geocodio API, which requires a different API key. (Again, only one person on the team should do this step, then they should check in the credentials file for everyone else to update from.)
- Go to console.cloud.google.com, create a new project, go to APIs & Services > Credentials, then add new
OAuth 2.0 Client IDsfor a web application. Copy theGOOGLE_CLIENT_IDandGOOGLE_CLIENT_SECRETand add them to yourcredentials.yml.enc. Make sure to set your callback/redirect URL on the Google Developer Console using your deployed app’s hostname:https://YOUR-DEPLOYED-HOSTNAME/auth/google_oauth2/callback.
- Go to github.com/settings, then navigate to Developer Settings and click on
OAuth appsand add a newOAuth App. Copy theGITHUB_CLIENT_IDandGITHUB_CLIENT_SECRETand add them to yourcredentials.yml.enc. As before, use your deployed app’s hostname for the callback URL:https://YOUR-DEPLOYED-HOSTNAME/auth/github/callback.
- Get a Geocodio API key. Create an account, then visit the Geocodio API page. One person should create an API key and share it with the team.
Geocodio is a free service with a very easy JSON API for looking up representatives by a location. We’ve taken care of the main work of setting up the API, but you’ll need to pass in a GEOCODIO_API_KEY. Check out their documentation.
- Commit and push your changes to GitHub, then deploy using the instructions for your platform. At this point, visit your deployed app and verify that you can log in with GitHub or Google. You should also be able to go to the Representatives page and search for a location.
CI: GitHub Actions
GitHub Actions are scripts that can be run each time code is pushed to GitHub. These scripts run in a virtual machine container, so they can install more or less whatever they need each time they are run. We will use GitHub Actions to run all of our app’s tests on each code push.
Each step of an action can either be coded manually, or can reference an external already-published action, like a subroutine. The provided file .github/workflows/specs.yml contains a combination of these: it installs Node, Ruby and Rails; runs Bundler and npm to install dependencies; and then runs all the app’s tests (RSpec, Cucumber, and the accessibility profile) and reports coverage. The linters run in a separate workflow, .github/workflows/linters.yml, on each pull request. Note that each time a workflow runs, it is basically like starting with a “blank” machine image, though caching is used intelligently by particular action steps to avoid needless repeated work on each run.
The presence of this file in the repo is enough to trigger the workflows on each push. When using encrypted credentials, Rails needs to decrypt credentials.yml.enc in CI just as it does in the deployed app, so we need to make the decryption key available to GitHub. GitHub provides a mechanism called GitHub Secrets that allows setting environment variables visible to workflows; a key to this mechanism is that even if a repo is public, its secrets are always private.
So in your repo settings, add a GitHub app secret for RAILS_MASTER_KEY (you may find this guide useful) and set the value to the contents of your local config/master.key. This will cause the value of the secret to be “visible” to GitHub Actions workflows as the environment variable RAILS_MASTER_KEY.
CAUTION: If using copy-paste to copy the long contents of the key file, be careful not to accidentally include any extra spaces or newlines when pasting to GitHub.
You will then need to uncomment the RAILS_MASTER_KEY line in the env: block of the specs.yml workflow, which references the secret, so that the CI workflow can successfully decrypt the credentials file and use the values therein.
Test the GitHub Action
The GitHub workflow specs.yml will trigger automatically on each push, but you can also test it manually: navigate to your repo, click Actions, in the main repository navigation, click the workflow you want to run in the left sidebar (“All Specs”, defined in specs.yml), and then click Run Workflow.
You can add a GitHub Workflow badge to your repo’s README to indicate whether the most recent CI run passed or failed, and what the code coverage is. To add the “workflow passing” badge, you can add the following code to put a dynamically generated badge file into your README.md:

Tracking Tasks Using GitHub Projects
An issue is something that needs to be done to the codebase: bug fix, new feature, documentation fix, and so on. A key feature of issues is how they connect to development: you can link any issue to one or more branches, which makes branch-per-feature development (textbook section 10.2) easy to do, and you can link an issue to a pull request, so that successfully merging the PR (section 10.3) closes out the issue.
When you divide up work in the regular iterations, each story will be an Issue, and the person(s) assigned to that Issue will be the ones responsible for the code and tests of that story.
To keep track of your issues while you work on your project, GitHub Projects provides a dashboard with different stages for your issues (New, Todo, In Progress, In Review, Done).
Add a GitHub project to your repo
- Open your repo in GitHub
- In “Projects”, click on “New project” (not “Link a Project”) and, when asked for a template in the left column, select “[TEMPLATE] 10.5 Backlog Template”
Understand your GitHub project
Now that you successfully added a project to your repository, you can start creating issues!
- New/Ice Box: all unprioritized issues
- Todo: prioritized issues (you’re going to do the work)
- In Progress: issues in progress
- In Review: issues pending review from your teammates (make sure you make a PR!)
- Done: issues you finished working on
Deliverables
There is no direct deliverable for iteration 0. You will need to complete this iteration (and potentially refer back to it) before starting iteration 1, however. Your course staff may verify that you’ve completed these steps before grading iteration 1.