firebase-ci

Simplified Firebase interaction for continuous integration

Features

• Deploy to different Firebase projects based on Git Branch
• Automatically use commit message as deploy message
• Expose CI environment variables based on branch name
• Mapping of CI environment variables to Firebase Functions Config
• Optional Deploying of targets Functions, Hosting, Database (rules) and Storage (rules)
• Skip For Pull Requests

Getting Started

1. Generate a CI token through firebase-tools by running firebase login:ci

2. Place this token within your CI environment under the variable FIREBASE_TOKEN

3. Install firebase-ci into your project (so it is available on your CI): npm install --save-dev firebase-ci firebase-tools. If you don't want firebase-tools as a dev dependency, it can be left out as it is installed automatically if it doesn't exist.

4. Set different Firebase project names in projects parameter of .firebaserc. The project aliases should match branch names like so:

   {
     "projects": {
       "prod": "prod-firebase",
       "master": "dev-firebase",
       "default": "dev-firebase"
     }
   }

5. Add calls to the scripts within to your CI stages, here are a few example snippets:

   Github Actions (.github/workflows/*.yml)

   jobs:
     deploy:
       name: ${{ matrix.app }} Deploy
       runs-on: ubuntu-18.04
       steps:
         - name: Checkout Code
           uses: actions/checkout@v2
         
         ## Place other steps for installing deps, building, etc. here
         ## See the github-actions example for a full workflow
   
         # Deploy to Firebase project matching branch name in projects parameter of .firebaserc
         - name: Deploy To Firebase
           run: |
             $(npm bin)/firebase-ci deploy

   Travis (travis.yml)

   script:
     # Deploy to Firebase project matching branch name in projects parameter of .firebaserc
     - $(npm bin)/firebase-ci deploy

   NOTES:

   • firebase-ci can be used through the nodejs bin OR installed globally (npm bin is used here since instructions include adding firebase-ci as a dev dependency)
   • firebase-tools will be installed (from @latest) if it is not already installed locally or globally

Setting Project

There are a number of ways to set which Firebase project within .firebaserc is being used when running actions. Below is the order of for how the project is determined (default at bottom):

• FIREBASE_CI_PROJECT environment variable (overrides all)
• branch name (dependent on CI provider):
  • Github Actions - GITHUB_HEAD_REF or GITHUB_REF (refs/heads/ prefix is removed)
  • Travis-CI - TRAVIS_BRANCH
  • Gitlab - CI_COMMIT_REF_SLUG
  • Circle-CI - CIRCLE_BRANCH
  • wercker - WERCKER_GIT_BRANCH
  • drone-ci - DRONE_BRANCH
  • codeship - CI_BRANCH
  • bitbucket - BITBUCKET_BRANCH
• fallback name (dependent on CI provider)
  • Gitlab - CI_ENVIRONMENT_SLUG
• master
• default (must be set within .firebaserc)

Examples

Examples are the same basic html file upload to Firebase hosting of different projects (or "environments") for different CI providers:

• Travis
• Github Actions

Why?

Advanced configuration of Firebase deployment is often necessary when deploying through continuous integration environment. Instead of having to write and invoke your own scripts, firebase-ci provides an easy way to create/modify advanced configurations.

FAQ

1. What about Travis's firebase deploy option?

   Using the built in travis firebase deploy tool is actually a perfect solution if you want to do general deployment. You can even include the following to install stuff functions dependencies on Travis:

   after_success:
     - npm install --prefix ./functions
   
   deploy:
     provider: firebase
     project: $TRAVIS_BRANCH
     skip_cleanup: true
     token:
       secure: $FIREBASE_TOKEN

   This lets you deploy to whatever instance you want based on your branch (and config in .firebaserc).

   firebase-ci is for more advanced implementations including only deploying functions, hosting

Commands

• copyVersion - Copy version from package.json to functions/package.json
• createConfig - Create a config file based on CI environment variables (defaults to src/config.js)
• deploy - Deploy to Firebase project matching branch name in .firebaserc (runs other firebase-ci actions by default unless -s is passed)
• serve - Serve a the Firebase project matching branch name in .firebaserc using firebase serve
• mapEnv - Map environment variables from CI Environment to Firebase functions environment
• project - Output project name associated with CI environment (useful for commands that should be run for each environment)

copyVersion

It can be convenient for the version within the functions/package.json file to match the top level package.json. Enabling the copyVersion option, automatically copies the version number when calling deploy if the following config is provided:

"ci": {
  "copyVersion": true
}

setEnv

Expose environment variables to CI based on current branch.

With a .firebaserc that looks like so:

"ci": {
  "setEnv": {
    "master": {
      "SOME_VAR": "some value"
      "REACT_APP_ENV_VARIABLE": "val passed to react app"
    },
    "prod": {
      "SOME_VAR": "some other value"
      "REACT_APP_ENV_VARIABLE": "val passed to react app"
    }
  }
}

SOME_VAR and REACT_APP_ENV_VARIABLE will be exposed to environment variables of your CI based on branch. Meaning that on the master branch SOME_VAR will be set to "some value"

createConfig

DEPRECATED

Create a config file based on CI environment variables (defaults to src/config.js). Allows for creating files of different types based on the extension passed.

With the following environment variables: GA_TRACKINGID - Your google analytics tracking id INT_FIREBASE_WEBAPIKEY - API key of your integration/main Firebase instance (this can also be hard coded if you prefer since it doesn't) PROD_FIREBASE_WEBAPIKEY - API key of your production Firebase instance

And a .firebaserc that looks like so:

"ci": {
  "createConfig": {
    "master": {
      "version": "${npm_package_version}",
      "gaTrackingId": "${GA_TRACKINGID}",
      "firebase": {
        "apiKey": "${INT_FIREBASE_WEBAPIKEY}",
        "authDomain": "firebase-ci-int.firebaseapp.com",
        "databaseURL": "https://firebase-ci-int.firebaseio.com",
        "projectId": "firebase-ci-int",
        "storageBucket": "firebase-ci-int.appspot.com"
      }
    },
    "prod": {
      "version": "${npm_package_version}",
      "gaTrackingId": "${GA_TRACKINGID}",
      "firebase": {
        "apiKey": "${PROD_FIREBASE_WEBAPIKEY}",
        "authDomain": "firebase-ci.firebaseapp.com",
        "databaseURL": "https://firebase-ci.firebaseio.com",
        "projectId": "firebase-ci",
        "storageBucket": "firebase-ci.appspot.com"
      }
    }
  }
}

building on master branch, produces a file in src/config.js that looks like so:

export const version = "0.0.1" // or whatever version your package is
export const gaTrackingId = "123GA" // your google analytics tracking ID

export const firebase = {
  apiKey: "<- your app API key ->",
  authDomain: "<- your app name ->.firebaseapp.com",
  databaseURL: "https://<- your app name ->.firebaseio.com",
  projectId: "<- your app name ->",
  storageBucket: "<- your app name ->.appspot.com"
}

export default { version, gaTrackingId, firebase }

Options

Options can be passed as flags or within an options object if calling action as a function

--project - Project within .firebaserc to use when creating config file. Defaults to "default" then to "master" --path - Path to save the config file. Defaults to src/config.js

deploy

firebase-ci deploy

Options:

• Simple mode
• Info
• Only

Deploy to Firebase. Following the API of firebase-tools, specific targets (i.e. functions, hosting) can be specified for deployment.

Default

• Everything skipped on Pull Requests
• Deployment goes to default project
• If you have a functions folder, npm install will be run for you within your functions folder
• copyVersion is called before deployment based on settings in .firebaserc, if you don't want this to happen, use simple mode.
• mapEnv is called before deployment based on settings in .firebaserc, if you don't want this to happen, use simple mode.

Simple Mode

Option: --simple Flag: -s

Skip all firebase-ci actions and only run Firebase deployment

Info Option

Option : --info Flag: -i

Provide extra information from internal actions (including npm install of firebase-tools).

Only Option

Option : --only Flag: -o

Firebase targets to include (passed directly to firebase-tools)

Except Option

Option : --except

Deploy to all targets except specified (e.g. "database")

Force Option

Option : --force Flag: -f

Delete Cloud Functions missing from the current working directory without confirmation

Skipping Deploying Functions

If you have a functions folder, your functions will automatically deploy as part of using firebase-ci. For skipping this functionality, you may use the only flag, similar to the API of firebase-tools.

script:
  - $(npm bin)/firebase-ci deploy --only hosting

serve

firebase-ci serve

Options:

• only

Serve using to firebase serve. Following the API of firebase-tools, specific targets (i.e. functions, hosting) can be specified for serving.

Default

• Project alias matching branch name is served
• If there is no matching alias, default project is used

Only Option

Option : --only Flag: -o

Firebase targets to include (passed directly to firebase-tools)

mapEnv

firebase-ci mapEnv

Set Firebase Functions variables based on CI variables. Does not require writing any secure variables within config files.

NOTE: Called automatically during firebase-ci deploy

Set the mapEnv parameter with an object containing the variables you would like to map in the following pattern:

TRAVIS_VAR: "firebase.var"

Example

CI variable is SOME_TOKEN="asdf" and you would like to set it to some.token on Firebase Functions you would provide the following config:

"ci": {
  "mapEnv": {
    "SOME_TOKEN": "some.token"
  }
}

Internally calls firebase functions:config:set some.token="asdf". This will happen for every variable you provide within mapEnv.

skipDependenciesInstall

Skip installing of dependencies including firebase-tools and node_modules within functions folder

skipToolsInstall

Skip installing of firebase-tools (installed by default when calling firebase-ci deploy without simple mode)

skipFunctionsInstall

Skip running npm install within functions folder (npm install is called within functions folder by default when calling firebase-ci deploy).

project

Get name of project associated with the CI environment

Example

echo "Project to deploy to $(firebase-ci project)"

projectID

Get the projectId associated with the CI environment. Initially loaded from ci.createConfig.${branchName}.firebase.projectId and falls back to project from project command

Example

echo "Project ID from config $(firebase-ci projectId)"

branch

Get the branch associated with the CI environment (loaded from environment variables)

Example

echo "Branch name from ci env $(firebase-ci branch)"

Roadmap

• setCORS option for copying CORS config file to Cloud Storage Bucket
• only setting non existent env vars with mapEnv
• Support for Continuous Integration Tools other than Travis-CI