firebase-ci

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

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

• Place this token within your CI environment under the variable FIREBASE_TOKEN

• 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.

• 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"
    }
  }
  

• 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

• 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